Wilby DocsGet Sandbox Keys

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.

CodeWhat it means
above_bank_authorizationAbove what the customer's bank authorization allows.
above_bank_monthly_limitAbove the bank authorization's monthly limit.
acp_one_timeThe order was paid with a one-time agent payment token; nothing more can be charged. The agent starts a new checkout.
agent_mandate_invalidA signed permission from the agent platform doesn't check out (details in the message).
agent_mandates_invalidThe signed permissions from the agent platform don't check out together.
agent_not_allowedYour agent access settings don't allow this AI agent.
agent_rulesYour own AI agent rules refused it (most per order, hours).
already_decidedThe customer already answered.
already_deliveredThe order is already marked delivered.
already_doneThis was already allowed.
already_paidAlready paid; refund it instead.
already_resolvedThe dispute was already settled.
already_signed_inThis sign-in was already completed; the customer starts again.
already_tippedA tip was already added with this link.
amount_range_requiredThe signed permission must set a most-per-payment amount.
apps_not_setAdd your app first (POST /v1/settings apps).
awaiting_customerThe customer hasn't answered the incremental charge yet.
bad_jsonNot JSON.
bad_signatureThe webhook signature didn't check out.
bank_account_refusedThe processor refused the bank account (reason in the message).
bank_authorization_endedThe customer's bank authorization ended.
bank_authorization_requiredA bank payment needs the customer's ACH debit authorization first.
business_rulesYour business rules refused it.
card_chargebackCard chargebacks are decided by the card network, not here.
catalog_neededGoogle agent checkout sells from your catalog: your storefront must answer catalog.
ceremony_expiredThe Face ID / fingerprint prompt timed out; start again.
ceremony_usedThe prompt was already used; start again.
code_expiredThe code expired; ask for a new one.
code_limitWith a texted code, a per-order limit can be at most $100.
code_not_sentThe code couldn't be sent; try again.
code_usedThe code was already used.
codes_unavailableCodes aren't available for this store.
confirm_statementsTick each statement to confirm it.
customer_approval_neededThe customer has to approve this themselves.
customer_mismatchThis order belongs to another customer.
customer_no_payment_methodThe customer has no saved payment method.
dispute_openA dispute for this order is already being reviewed.
dispute_window_closedToo long after the order was captured to open a dispute.
duplicate_external_refAn order with this external_ref already exists.
duplicate_reportThis payment was already reported (safe to ignore on a retry).
email_not_sentThe email couldn't be sent.
email_unavailableEmail isn't set up on this server.
estimate_above_mandateThe amount is above what the agent committed in its signed checkout.
evidence_requiredAn incremental charge needs at least one piece of evidence.
forbiddenNot allowed for this customer or key.
host_takenThat address is already in use on Wilby.
idempotency_key_requiredPOST requests need an Idempotency-Key header.
idempotency_key_reusedThis Idempotency-Key was used for a different request.
incremental_charge_not_payableThat incremental charge isn't approved, is already paid, or is smaller than this payment.
incremental_charge_pendingAn incremental charge is already waiting for the customer. Withdraw it or wait.
incremental_charge_requiredThe final price is above what was paid: ask for an incremental charge first.
internalSomething went wrong on Wilby's side. Try again; nothing was done twice.
invalid_agent_accessAgent access settings aren't valid (details in the message).
invalid_agent_checkThe agent check can't be used here (send agent_check_id on its own).
invalid_agent_keyTest tools: the agent key isn't a P-256 public JWK.
invalid_agent_rulesAI agent rules aren't valid (details in the message).
invalid_amountThe amount isn't valid.
invalid_amountThe amount must be at least $1.
invalid_api_keyThe key isn't valid.
invalid_appsApp settings aren't valid.
invalid_auth_methodauth_method is client_secret_basic or private_key_jwt.
invalid_choiceThat choice isn't one of the options.
invalid_choicesChoose 1 to 4 of the allowed percents.
invalid_codeThe code isn't valid or has expired.
invalid_colorColors look like #1E3059.
invalid_companyEnter the company name.
invalid_customer_initiatedcustomer_initiated is only for a payment after the order is paid.
invalid_dateDates are YYYY-MM-DD.
invalid_daysChoose how long it lasts.
invalid_descriptionDescribe the order.
invalid_disputeChoose what went wrong.
invalid_emailEnter a valid email.
invalid_embed_originsembed_origins: up to 5 https origins.
invalid_expires_atexpires_at isn't a valid date.
invalid_google_partner_idgoogle_partner_id: letters, numbers, - and _ only.
invalid_hostThat 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_itemsAdd at least one item.
invalid_jsonThe request body isn't valid JSON.
invalid_jwks_uriprivate_key_jwt needs jwks_uri.
invalid_keysThe processor keys aren't in the right format.
invalid_kindChoose what kind of company you are.
invalid_limitA limit is outside the allowed range.
invalid_listingA listing field isn't valid (plain text, length).
invalid_logoThe logo must be a PNG or JPEG data URI under 150 KB.
invalid_max_amountmax_amount_cents can't be below amount_cents.
invalid_nameGive a name (up to 60 characters).
invalid_overageCheck the choices.
invalid_rangeThe automatic range must be between $0 and the per-order limit.
invalid_recommendedThe recommended choice must be one of the choices.
invalid_redirect_uriredirect_uris: 1 to 10 https addresses.
invalid_requestThis code was for something else.
invalid_responseThe browser's answer couldn't be read (not WebAuthn JSON). An integration bug, not the customer.
invalid_return_urlreturn_url must be https or your app's own link.
invalid_screen_originsscreen_origins: up to 10 https origins.
invalid_screen_passThe screen pass is missing or not valid.
invalid_staff_namestaff_name: the name of the person opening the Dashboard.
invalid_stageNot possible at this order stage.
invalid_statementsStatements aren't valid (details in the message).
invalid_storefrontStorefront settings aren't valid (details in the message).
invalid_storesChoose at least one store.
invalid_stripe_keyThe Stripe key isn't usable (details in the message).
invalid_tipChoose a tip amount.
invalid_tracking_urltracking_url must be https.
invalid_tztz must be an IANA time zone.
invalid_ucpGoogle agent checkout settings aren't valid.
invalid_urlThe address isn't usable (details in the message).
invalid_user_keyTest tools: the device key isn't a P-256 public JWK.
invalid_wordingUnknown wording key.
issuer_not_trustedThe signer of this permission isn't trusted. Add it as a trusted issuer.
keys_refusedThe processor didn't accept these keys.
line_items_not_allowedThe order doesn't match what the customer allowed.
link_expiredThe link expired.
link_not_usableThe link expired or was already used.
link_replacedA newer link was sent; use the newest one.
mandate_already_usedThis closed permission was already used; the agent signs a new one.
mandate_expiredThe signed permission expired.
mandate_not_yet_validThe signed permission isn't valid yet.
mandate_other_customerThis permission belongs to a different customer.
mandate_staleThe agent signed too long ago (or in the future).
max_orders_reachedThe permission's most orders was reached.
merchant_no_processorThe store has no active processor account.
merchant_not_foundNo store with that id.
needs_customerAbove the customer's limits: the customer approves it themselves (message says what to tell them).
no_payment_methodNo saved payment method to charge.
not_allowedWilby didn't allow it (for the one-call hold: release the hold and cancel your order).
not_an_outside_agent_orderagent_mandates only apply to orders from an outside agent.
not_connectedThe store has no connected account for that processor.
not_foundNot found.
not_pausedIt isn't paused.
not_pendingAlready answered (approved, declined, expired or withdrawn).
not_shippedReport the shipment before delivery.
not_supported_by_processorThe processor doesn't support this.
nothing_owedNothing is owed on this order.
openhold_runs_paymentsWilby runs payments for you; use authorize / capture instead of reporting.
order_expiredThe order expired; any hold was released.
origin_not_allowedThis website isn't in your screen_origins.
over_budgetOver the customer's budget in the signed permission.
over_monthly_limitOver the customer's monthly limit.
over_order_limitOver the customer's per-order limit.
partner_refusedYour Storefront API refused it. Your message is passed on, with the next step for standard codes.
partner_runs_paymentsYou run payments: retry at your processor, then report it.
partner_unavailableYour Storefront API didn't answer.
passkey_failedThe passkey answer didn't check out (cancelled, another passkey, or a bad signature). Let them try again.
payment_declinedThe bank or card refused it.
payment_method_not_supportedThis store doesn't take that payment method.
permission_endedThe permission was turned off or expired.
permission_pausedThe permission is paused until the customer turns it back on.
processor_failedThe processor refused it.
processor_no_answerThe processor hasn't confirmed yet. Nothing was recorded; retrying is safe.
processor_not_configuredThat processor isn't set up on this server yet.
processor_reports_thisWilby gets this from the processor directly; don't report it.
processor_sandbox_onlyThis processor is for sandbox only.
processor_unsupportedThis processor isn't supported.
proof_requiredApproving needs the customer's proof (passkey or code).
quote_expiredThe price expired; get a new quote.
quote_usedAn order was already placed from this quote.
range_too_longThe date range is too long.
rate_limitedToo many requests; wait a few minutes.
refund_requiredGive refund_cents when refunding.
refund_too_largeMore than can be refunded.
report_inconsistentThe report breaks the money rules (capture above the hold, refund above what was captured).
request_expiredThe request expired.
request_in_progressA request with this Idempotency-Key is still running.
retry_limitThis debit was already retried the most times bank rules allow.
retry_not_allowedThis bank return can't be retried.
retry_window_passedToo long ago to retry.
sandbox_onlySandbox keys only.
screen_pass_expiredThe screen pass expired; ask your server for a new one.
sign_in_requiredThe customer has to connect (sign in) first. Browsing works without it.
slug_takenAnother business uses this storefront slug.
square_no_locationThe Square account has no location to take payments at.
store_errorThe store's system had an error.
store_existsA store with this id already exists.
store_not_allowedThe customer didn't allow orders at this store.
store_not_readyThis store can't take orders yet.
store_view_onlyA one-store view is view only.
storefront_not_readyThe storefront isn't set up yet.
storefront_offTurn the storefront on first.
storefront_secret_missingCreate the storefront secret first (POST /v1/storefront/secret).
too_many_attemptsToo many wrong tries; wait or ask for a new code.
too_many_codesToo many codes asked for; wait a few minutes.
too_many_endpointsToo many webhook endpoints.
too_many_requestsToo many requests; wait a few minutes.
too_many_shipmentsAt most 20 shipments per order.
tracking_requiredA shipment needs the carrier and tracking number.
unauthorizedMissing or invalid key.
under_minimumBelow the minimum the customer allowed.
unknown_toolUnknown tool name.
unsupported_recurrenceThat repeat schedule isn't supported yet.
waiting_for_customerThe customer is approving this right now; wait for their answer.
webhook_not_addedThe processor took the keys but Wilby couldn't add its webhook.
webhook_not_configuredWebhooks aren't set up on this server.
work_email_neededUse a work email.
wrong_codeThe code isn't right (the message says how many tries are left).
wrong_storeThe 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).