Errors

Status codes, error shapes, and how to recover from each kind of failure.

Error format

Every error — every 4xx and 5xx — is JSON with an error and a code:

{ "error": "amount must be greater than 0", "code": "bad_request" }

code is the contract; error is prose for a human and may be reworded in any release. Where the API can say more than the status, code is specific — see Authentication errors and Common 422 responses below, idempotency_key_reused, rate_limited. Otherwise it is derived from the status:

Any other 4xx is client_error and any other 5xx is server_error. A response may gain a more specific code in a later release, so branch on the codes you know and handle any other code by its HTTP status.

Authentication errors

Authentication failures use the same JSON envelope, and always carry a code:

{ "error": "invalid authorization token", "code": "invalid_api_key" }

Every 401 also carries WWW-Authenticate: Bearer.

A request no route serves answers 404 with code not_found, and a known path called with the wrong method answers 405 with code method_not_allowed. Operations live under /payments-api/v1; a request to an operation under /payments-api/v2 — the documentation prefix — says so in its error.

Machine-walkable support path

The currently supported error-to-support path is described by this stable object. It is a documentation contract, not an assertion that every runtime error response already contains a docsUrl field (that response change is reserved for the PAY-16 contract).

{
  "supportPath": {
    "errorGuide": "/payments-api/v2/docs/errors.md",
    "agentIndex": "/payments-api/v2/llms.txt",
    "escalation": {
      "kind": "email",
      "address": "support@fynex.ai",
      "required": ["requestId", "httpStatus", "responseBody", "occurredAt"]
    }
  }
}

An automated client should fetch errorGuide, then use agentIndex to find the relevant skill or guide. Until a structured escalation endpoint is published, send the listed fields to support@fynex.ai; requestId is the value of the X-Request-Id response header. Do not put bearer tokens, cardholder data, or secrets in responseBody. The email route is the current supported escalation mechanism; it is not a promise that an API endpoint exists.

Status codes

Common 400 responses

Common 409 responses

These mean the resource's current state forbids the action. Read the message before deciding whether to retry:

Common 422 responses

POST /initialize-payment answers 422 when the card itself is refused before authorization; no funds moved, and re-sending the same card fails identically — so, unlike a 502, this is not a retry signal. Branch on code:

{ "error": "This card type is not accepted for this payment. Please use a different card.", "code": "card_brand_not_supported" }

The payment is still created, in failed with the matching failureCode, so GET /payments-api/v1/payments/{externalOrderRef} shows it. Replaying the same Idempotency-Key with the same body returns the same 422 and code; to try another card, send a new Idempotency-Key. A replay reflects the payment's current failure, so it answers from the stored payment rather than repeating the first response verbatim. Treat an unrecognised code as a refusal you cannot fix automatically — new codes may be added. A generic HTTP client or SDK that treats 4xx as non-retryable is doing the right thing here.

A checkout session or payment link no terminal can take

POST /checkout and POST /api/v1/payment-links answer 422 with code currency_not_supported when none of the account's payment terminals can take the payment — most often a currency the account has no terminal for (a GBP session on an account with only EUR terminals), or, for a declared countryCode, a country none of them serves. Nothing is created: no session, no payment, no link.

{ "error": "currency GBP is not supported for country GB on this account", "code": "currency_not_supported" }

The check runs at creation so the customer never reaches a checkout that would fail with 1003 (routing) after they press pay. A session is accepted when any method the hosted checkout can offer for it would route: the card form, or a local payment method the account has a terminal for in that currency and country. A payment link lives longer than a session, so it is refused only when the account has no terminal that matches the link's currency, mode (live or test) and payment type and country; a matching terminal that is temporarily suspended, or not effective yet, does not block the link.

The same request succeeds once the account has a terminal for that currency (and country), for example after the currency is activated on the account — ask Fynex support to enable it. Until then, re-sending it gives the same 422. Replaying an Idempotency-Key that already created a session still returns that session. If Fynex cannot check the terminals at that moment (a transient internal error), the session or link is created rather than refused.

Rate limiting (429 responses)

When the per-seller limiter is enabled and available, authenticated business operation endpoints under /payments-api/v1/* are rate-limited using a token-bucket keyed on the authenticated seller_account_id. The standard budget is 100 requests per hour per seller. An account or environment with a provisioned exception can have a different budget, so read X-RateLimit-Limit and X-RateLimit-Remaining from the response: they are authoritative for the environment you are calling. The budget is per-seller (one noisy client cannot starve others).

A Demo account has its own, larger budget: 200 requests per minute per seller, counted separately from the Live budget. Test traffic — including a coding agent that lists, polls and retries in a loop — does not run into the Live limit, and switching an account to Live does not carry Demo usage over.

Every authorized response — both 200 and 429 — normally carries:

Note

RateLimit and RateLimit-Policy are the current standards-track fields (draft-ietf-httpapi-ratelimit-headers). They are not the RateLimit-Limit / RateLimit-Remaining / RateLimit-Reset triple you may remember — that spelling is from an earlier revision of the same draft and Fynex does not send it. If your client only knows the old shape, read the X-RateLimit-* headers, which carry the same numbers.

X-RateLimit-Reset is what lets you pace a loop before you are refused: X-RateLimit-Remaining alone tells you how many requests are left but not how long you have to spend them over, and Retry-After arrives only once you have already been throttled.

When the bucket is empty:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 36
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 3600
RateLimit-Policy: "seller";q=100;qu="requests";w=3600
RateLimit: "seller";r=0;t=3600

{"error":"rate limit exceeded; retry after the Retry-After header value","code":"rate_limited"}

Every 429 carries Retry-After, and a limiter's 429 carries code rate_limited. If the limiter itself is unavailable on a route that fails closed, the answer is 503 with Retry-After: 1 and code temporarily_unavailable.

How to react: sleep for at least Retry-After seconds, then retry the same request with the same Idempotency-Key. Idempotency-Key replay is safe; the original response is returned once the bucket has capacity.

How to avoid it: read X-RateLimit-Remaining and X-RateLimit-Reset on every response and back off proactively when the remaining count approaches zero. Drive your polling interval from those values rather than from a fixed number of seconds — an account-specific budget can differ from the standard one. Add ±20% jitter to any loop.

Missing headers: authorized responses — both 2xx and 429 — normally carry the X-RateLimit-* headers. 401/403 responses never do, because the budget is keyed on the authenticated seller and the limit is applied after authentication. A deployment may disable the limiter, and a temporary limiter outage can allow an authorized request without rate-limit headers. If the headers are absent, hold your most conservative polling interval rather than reading it as headroom, and contact support if it persists.

502 vs 500

• 502 Bad Gateway — Fynex called an upstream processor and it returned a non-OK response or timed out. The action may or may not have been processed upstream — your idempotency key protects you on retry.
• 500 Internal Server Error — Fynex itself encountered an unexpected error. Should be rare. If you see persistent 500s, contact support with the request details.

Common 502 causes

A 502 can come from either Fynex-side routing (no terminal selected) or an upstream processor returning a non-OK response. An unsupported APM market is instead rejected with 400 before routing. Upstream-side 502s all share the same body shape:

{ "error": "upstream card processor returned <status>" }

To distinguish why the upstream rejected the request, fetch the payment afterwards (GET /payments-api/v1/payments/{externalOrderRef}) and inspect its failureCode + failureStage fields.

Failure codes inside payment responses

Even when the HTTP call returns 200, the payment itself may have failed at the processor. Inspect the response body:

{
  "paymentId": "ORDER-1042",
  "status": "failed",
  "lifecycleStatus": "failed",
  "legacyStatus": "failed",
  "failureCode": 2001,
  "retry": "never",
  "failureCategory": "hard",
  "failureDescription": "Provider declined the transaction"
}

failureCode is the contract; failureDescription is prose for a human and may be reworded in any release, so branch on the code and show the description. Every code is enumerated below with its cause, whether retrying can succeed, and what to do — and the same table is on the field itself in openapi.json, so a generated client carries it. The retry verdict also rides on the response as retry (safe, fix_first or never), on every payment and refund response and on the PaymentCompleted webhook, so you can branch on it without joining the table yourself.

The retry column is the part worth reading twice. Getting it wrong costs money in both directions: retrying a decline the issuer already made loses the sale and can get the card blocked, while not retrying a timeout with the original Idempotency-Key is how a customer gets charged twice.

failureCategory rides beside it and answers the other question — not what to do but what happened: hard, transient, requires_change, integration_error, cancelled, or unknown for a code this catalogue does not classify. Branch your retry loop on retry; count, chart and alert on failureCategory. The split is what keeps a spike of integration_error (your bug) out of the same number as a spike of hard (your conversion rate). Both fields are absent while the payment has not failed.

failureStage narrows it further — the stage says where the payment stopped, the code says why. Anything before authorization never reached a provider, so no money moved.

Two card declines that leave a hold

A declined payment is not always a released card. On an AVS mismatch — the billing address or postal code did not match the issuer's record — the issuer may have placed a temporary authorization hold that the cardholder sees on their statement for up to 3–5 business days even though the payment failed and Fynex captured nothing. The same is true on a CVV mismatch: the security code was wrong, the payment failed, and the cardholder may still see a pending authorization for up to 3–5 business days before their issuer drops it.

Neither hold is something Fynex can release, and neither is a charge. Say so in your own customer-facing copy before the buyer calls their bank — and do not re-run the same card repeatedly to "clear" it, because each attempt can add another hold.

An AVS refusal has its own code: failureCode: 2005 (address verification failed, failureCategory: requires_change) — the buyer must correct the billing address, not retry. A CVV mismatch is still reported as an ordinary 2001, and avsResult / cvvResult are not published on the payment, so for CVV the advice above applies only when you already know the decline reason from your own checkout flow.

Soft declines and 3-D Secure

3002 is the one decline that is not a refusal of the card: the issuer soft-declined the authorization and asked for strong customer authentication instead. The card processor reports its own soft-decline code at the authorization gate and Fynex maps it onto 3002, so branch on 3002 rather than on any processor-specific number. It carries retry: fix_first and failureCategory: requires_change, not hard — re-run the payment through a 3-D Secure flow and it can succeed. Retrying without one fails identically, and counting it as a decline throws away a sale you can still make. See 3DS Authentication.

3003 is the customer walking away rather than the issuer asking: the customer was sent to 3-D Secure and did not complete it before the authentication session expired, so no authorization was ever attempted and nothing was charged. It also carries retry: fix_first and failureCategory: requires_change. Replaying the request with the same Idempotency-Key returns the same failed payment — the session it depended on is gone — so ask the customer to pay again and complete the verification step their bank shows them.

The /checkout Idempotency-Key pitfall

POST /checkout validates the Idempotency-Key header right after auth, in initFinalizeHeaderMiddleware. A missing or malformed key returns a JSON 400 — {"error":"Idempotency-Key header is required"} (header absent or empty) or {"error":"Idempotency-Key must be a valid UUID"} (value is not a UUID). A bad token still answers 401 first. If you see one of these 400s from /checkout, fix the Idempotency-Key header rather than your token.

Recovering from partial failures

If /initialize-payment returns 502 but you don't know whether the processor created or charged the payment:

1. Wait 30–60 seconds.
2. Retry the unchanged request with the same idempotency key. Fynex and its APM provider integration reuse the same provider-attempt idempotency key and byte-stable create body, so a timed-out APM create is reconciled instead of creating a second charge. If the charge is still awaiting buyer action, the replay returns the current redirect or Multibanco payment instructions again.
3. If the retry also fails, poll the canonical state. From a server-to-server backend the simplest path is GET /payments-api/v1/payments/{externalOrderRef} (bearer auth, same token). From cookie-session contexts use the GraphQL genericPayment(id) query instead.

The same pattern applies to /finalize-payment, /payments/{id}/capture, /payments/{id}/refund, and /payouts.

See also

• Polling & SSE — Verify payment and payout state by polling or server-sent events.
• Idempotency & retries — Make your retries safe with idempotency keys.

Payment failure codes

Returned as failureCode on every payment and refund response, and on the payment.completed webhook. A 200 does not mean the payment succeeded — read status, and when it is failed read this.

Why the payment failed. 0 means it has not.

Retry says what re-sending achieves: safe — the same request with the same Idempotency-Key can succeed; fix first — retrying unchanged fails identically, something has to change; never — a decision was made or the outcome is not knowable by re-sending, and an automatic retry is wrong.

Category says what KIND of failure it is: hard — a decision was made and it stands; transient — nothing was decided; requires_change — the customer's instrument or authentication has to change; integration_error — the request or the seller's configuration is wrong, not the customer's card; cancelled — the payment was called off; unknown — unclassified. Both ride on the response, as retry and failureCategory.

Payout failure codes

Why the payout failed. Absent while it has not.

In every case the held funds are returned to the seller's available balance before the payout is marked failed, so a failed payout never leaves money stranded — and no payout failure is retryable by simply re-sending the same request. Treat a failed payout as terminal, read failureMessage for what to tell the seller, and create a new payout only after the underlying cause is addressed.

The enumerated code list is not published yet; it is pending a rename that removes supplier-specific prefixes from four of the values.