Error Codes
Every error looks like {"error": "code", "message": "…", "details": {…}}. The code is stable; the message is plain words you can show or log. Most errors change nothing, so fixing the request and sending it again is safe.
| Code | What it means |
|---|---|
above_bank_authorization | Above what the customer's bank authorization allows. |
above_bank_monthly_limit | Above the bank authorization's monthly limit. |
acp_one_time | The order was paid with a one-time agent payment token; nothing more can be charged. The agent starts a new checkout. |
agent_mandate_invalid | A signed permission from the agent platform doesn't check out (details in the message). |
agent_mandates_invalid | The signed permissions from the agent platform don't check out together. |
agent_not_allowed | Your agent access settings don't allow this AI agent. |
agent_rules | Your own AI agent rules refused it (most per order, hours). |
already_decided | The customer already answered. |
already_delivered | The order is already marked delivered. |
already_done | This was already allowed. |
already_paid | Already paid; refund it instead. |
already_resolved | The dispute was already settled. |
already_signed_in | This sign-in was already completed; the customer starts again. |
already_tipped | A tip was already added with this link. |
amount_range_required | The signed permission must set a most-per-payment amount. |
apps_not_set | Add your app first (POST /v1/settings apps). |
awaiting_customer | The customer hasn't answered the incremental charge yet. |
bad_json | Not JSON. |
bad_signature | The webhook signature didn't check out. |
bank_account_refused | The processor refused the bank account (reason in the message). |
bank_authorization_ended | The customer's bank authorization ended. |
bank_authorization_required | A bank payment needs the customer's ACH debit authorization first. |
business_rules | Your business rules refused it. |
card_chargeback | Card chargebacks are decided by the card network, not here. |
catalog_needed | Google agent checkout sells from your catalog: your storefront must answer catalog. |
ceremony_expired | The Face ID / fingerprint prompt timed out; start again. |
ceremony_used | The prompt was already used; start again. |
code_expired | The code expired; ask for a new one. |
code_limit | With a texted code, a per-order limit can be at most $100. |
code_not_sent | The code couldn't be sent; try again. |
code_used | The code was already used. |
codes_unavailable | Codes aren't available for this store. |
confirm_statements | Tick each statement to confirm it. |
customer_approval_needed | The customer has to approve this themselves. |
customer_mismatch | This order belongs to another customer. |
customer_no_payment_method | The customer has no saved payment method. |
dispute_open | A dispute for this order is already being reviewed. |
dispute_window_closed | Too long after the order was captured to open a dispute. |
duplicate_external_ref | An order with this external_ref already exists. |
duplicate_report | This payment was already reported (safe to ignore on a retry). |
email_not_sent | The email couldn't be sent. |
email_unavailable | Email isn't set up on this server. |
estimate_above_mandate | The amount is above what the agent committed in its signed checkout. |
evidence_required | An incremental charge needs at least one piece of evidence. |
forbidden | Not allowed for this customer or key. |
host_taken | That address is already in use on Wilby. |
idempotency_key_required | POST requests need an Idempotency-Key header. |
idempotency_key_reused | This Idempotency-Key was used for a different request. |
incremental_charge_not_payable | That incremental charge isn't approved, is already paid, or is smaller than this payment. |
incremental_charge_pending | An incremental charge is already waiting for the customer. Withdraw it or wait. |
incremental_charge_required | The final price is above what was paid: ask for an incremental charge first. |
internal | Something went wrong on Wilby's side. Try again; nothing was done twice. |
invalid_agent_access | Agent access settings aren't valid (details in the message). |
invalid_agent_check | The agent check can't be used here (send agent_check_id on its own). |
invalid_agent_key | Test tools: the agent key isn't a P-256 public JWK. |
invalid_agent_rules | AI agent rules aren't valid (details in the message). |
invalid_amount | The amount isn't valid. |
invalid_amount | The amount must be at least $1. |
invalid_api_key | The key isn't valid. |
invalid_apps | App settings aren't valid. |
invalid_auth_method | auth_method is client_secret_basic or private_key_jwt. |
invalid_choice | That choice isn't one of the options. |
invalid_choices | Choose 1 to 4 of the allowed percents. |
invalid_code | The code isn't valid or has expired. |
invalid_color | Colors look like #1E3059. |
invalid_company | Enter the company name. |
invalid_customer_initiated | customer_initiated is only for a payment after the order is paid. |
invalid_date | Dates are YYYY-MM-DD. |
invalid_days | Choose how long it lasts. |
invalid_description | Describe the order. |
invalid_dispute | Choose what went wrong. |
invalid_email | Enter a valid email. |
invalid_embed_origins | embed_origins: up to 5 https origins. |
invalid_expires_at | expires_at isn't a valid date. |
invalid_google_partner_id | google_partner_id: letters, numbers, - and _ only. |
invalid_host | That isn't an address you can use: give one under your own domain, such as agents.yourbusiness.com (no https://, no path, not your domain itself, not Wilby's). |
invalid_items | Add at least one item. |
invalid_json | The request body isn't valid JSON. |
invalid_jwks_uri | private_key_jwt needs jwks_uri. |
invalid_keys | The processor keys aren't in the right format. |
invalid_kind | Choose what kind of company you are. |
invalid_limit | A limit is outside the allowed range. |
invalid_listing | A listing field isn't valid (plain text, length). |
invalid_logo | The logo must be a PNG or JPEG data URI under 150 KB. |
invalid_max_amount | max_amount_cents can't be below amount_cents. |
invalid_name | Give a name (up to 60 characters). |
invalid_overage | Check the choices. |
invalid_range | The automatic range must be between $0 and the per-order limit. |
invalid_recommended | The recommended choice must be one of the choices. |
invalid_redirect_uri | redirect_uris: 1 to 10 https addresses. |
invalid_request | This code was for something else. |
invalid_response | The browser's answer couldn't be read (not WebAuthn JSON). An integration bug, not the customer. |
invalid_return_url | return_url must be https or your app's own link. |
invalid_screen_origins | screen_origins: up to 10 https origins. |
invalid_screen_pass | The screen pass is missing or not valid. |
invalid_staff_name | staff_name: the name of the person opening the Dashboard. |
invalid_stage | Not possible at this order stage. |
invalid_statements | Statements aren't valid (details in the message). |
invalid_storefront | Storefront settings aren't valid (details in the message). |
invalid_stores | Choose at least one store. |
invalid_stripe_key | The Stripe key isn't usable (details in the message). |
invalid_tip | Choose a tip amount. |
invalid_tracking_url | tracking_url must be https. |
invalid_tz | tz must be an IANA time zone. |
invalid_ucp | Google agent checkout settings aren't valid. |
invalid_url | The address isn't usable (details in the message). |
invalid_user_key | Test tools: the device key isn't a P-256 public JWK. |
invalid_wording | Unknown wording key. |
issuer_not_trusted | The signer of this permission isn't trusted. Add it as a trusted issuer. |
keys_refused | The processor didn't accept these keys. |
line_items_not_allowed | The order doesn't match what the customer allowed. |
link_expired | The link expired. |
link_not_usable | The link expired or was already used. |
link_replaced | A newer link was sent; use the newest one. |
mandate_already_used | This closed permission was already used; the agent signs a new one. |
mandate_expired | The signed permission expired. |
mandate_not_yet_valid | The signed permission isn't valid yet. |
mandate_other_customer | This permission belongs to a different customer. |
mandate_stale | The agent signed too long ago (or in the future). |
max_orders_reached | The permission's most orders was reached. |
merchant_no_processor | The store has no active processor account. |
merchant_not_found | No store with that id. |
needs_customer | Above the customer's limits: the customer approves it themselves (message says what to tell them). |
no_payment_method | No saved payment method to charge. |
not_allowed | Wilby didn't allow it (for the one-call hold: release the hold and cancel your order). |
not_an_outside_agent_order | agent_mandates only apply to orders from an outside agent. |
not_connected | The store has no connected account for that processor. |
not_found | Not found. |
not_paused | It isn't paused. |
not_pending | Already answered (approved, declined, expired or withdrawn). |
not_shipped | Report the shipment before delivery. |
not_supported_by_processor | The processor doesn't support this. |
nothing_owed | Nothing is owed on this order. |
openhold_runs_payments | Wilby runs payments for you; use authorize / capture instead of reporting. |
order_expired | The order expired; any hold was released. |
origin_not_allowed | This website isn't in your screen_origins. |
over_budget | Over the customer's budget in the signed permission. |
over_monthly_limit | Over the customer's monthly limit. |
over_order_limit | Over the customer's per-order limit. |
partner_refused | Your Storefront API refused it. Your message is passed on, with the next step for standard codes. |
partner_runs_payments | You run payments: retry at your processor, then report it. |
partner_unavailable | Your Storefront API didn't answer. |
passkey_failed | The passkey answer didn't check out (cancelled, another passkey, or a bad signature). Let them try again. |
payment_declined | The bank or card refused it. |
payment_method_not_supported | This store doesn't take that payment method. |
permission_ended | The permission was turned off or expired. |
permission_paused | The permission is paused until the customer turns it back on. |
processor_failed | The processor refused it. |
processor_no_answer | The processor hasn't confirmed yet. Nothing was recorded; retrying is safe. |
processor_not_configured | That processor isn't set up on this server yet. |
processor_reports_this | Wilby gets this from the processor directly; don't report it. |
processor_sandbox_only | This processor is for sandbox only. |
processor_unsupported | This processor isn't supported. |
proof_required | Approving needs the customer's proof (passkey or code). |
quote_expired | The price expired; get a new quote. |
quote_used | An order was already placed from this quote. |
range_too_long | The date range is too long. |
rate_limited | Too many requests; wait a few minutes. |
refund_required | Give refund_cents when refunding. |
refund_too_large | More than can be refunded. |
report_inconsistent | The report breaks the money rules (capture above the hold, refund above what was captured). |
request_expired | The request expired. |
request_in_progress | A request with this Idempotency-Key is still running. |
retry_limit | This debit was already retried the most times bank rules allow. |
retry_not_allowed | This bank return can't be retried. |
retry_window_passed | Too long ago to retry. |
sandbox_only | Sandbox keys only. |
screen_pass_expired | The screen pass expired; ask your server for a new one. |
sign_in_required | The customer has to connect (sign in) first. Browsing works without it. |
slug_taken | Another business uses this storefront slug. |
square_no_location | The Square account has no location to take payments at. |
store_error | The store's system had an error. |
store_exists | A store with this id already exists. |
store_not_allowed | The customer didn't allow orders at this store. |
store_not_ready | This store can't take orders yet. |
store_view_only | A one-store view is view only. |
storefront_not_ready | The storefront isn't set up yet. |
storefront_off | Turn the storefront on first. |
storefront_secret_missing | Create the storefront secret first (POST /v1/storefront/secret). |
too_many_attempts | Too many wrong tries; wait or ask for a new code. |
too_many_codes | Too many codes asked for; wait a few minutes. |
too_many_endpoints | Too many webhook endpoints. |
too_many_requests | Too many requests; wait a few minutes. |
too_many_shipments | At most 20 shipments per order. |
tracking_required | A shipment needs the carrier and tracking number. |
unauthorized | Missing or invalid key. |
under_minimum | Below the minimum the customer allowed. |
unknown_tool | Unknown tool name. |
unsupported_recurrence | That repeat schedule isn't supported yet. |
waiting_for_customer | The customer is approving this right now; wait for their answer. |
webhook_not_added | The processor took the keys but Wilby couldn't add its webhook. |
webhook_not_configured | Webhooks aren't set up on this server. |
work_email_needed | Use a work email. |
wrong_code | The code isn't right (the message says how many tries are left). |
wrong_store | The checkout is for another store. |
HTTP status: 400 a field is wrong, 401 the key or code is wrong, 402 the payment was refused, 403 not allowed (limits, rules, access), 404 not found, 409 not possible right now (already done, wrong stage, waiting for the customer), 422 the request can't be used as sent, 429 too many tries, 5xx try again (nothing was done twice).