Errors

This page is the master reference for how a call to /api/v1/partner or /api/v2/public fails: which HTTP status you get, which of three body shapes carries it, and every machine-readable code the platform raises, with the condition and the remedy. Per-operation pages in the reference repeat the codes that apply to them; this page is derived from the same code paths.

Branch on the HTTP status first

Which check runs first

Shared middleware refuses in a fixed order, and the response only ever reflects the EARLIEST failing check. Fix problems in this order when debugging a client:

1. X-Correlation-Id malformed or sent twice → 400 correlation_id_invalid
2. X-Tenant-Id present at all (even empty) → 400, no code — fires even when the key is also wrong
3. API key → 401 / 403, or 429 if your IP has too many recent failures
4. Rate limits (per route, then tenant aggregate) → 429 rate_limited
5. Idempotency-Key missing or malformed (mutating calls) → 400 idempotency_key_invalid
6. Replay layer: a JSON body over 1 MiB → 413 idempotency_request_too_large; then an Idempotency-Key conflict → 409 idempotency_key_reused / idempotency_key_in_progress / idempotency_response_unavailable
7. Body binding → 400 with an errors map, no code
8. The operation itself → its own 404 / 409 / 422 / 403

The three body shapes

1. The envelope — every 409 and 422 the operation itself raises, and the 503 on the crypto reads:

{
  "success": false,
  "status_code": 422,
  "message": "Invalid conversion pair.",
  "data": { "code": "invalid_pair", "detail": "from_currency and to_currency are required and must be different." }
}

data.code is always present. success and status_code repeat the HTTP status; message is human-readable and not stable.

2. The flat ErrorResponse — every 404, and the 403/409 raised by policy gates:

{ "title": "Customer was not found.", "detail": "No customer exists for the authenticated tenant and customer id.", "status": 404, "code": null }

code is null on every 404 and populated only by the gates listed under Policy-gate codes.

3. RFC 7807 application/problem+json — written by shared middleware for 400, 401, 403 (scope/IP), 409 and 413 (idempotency) and 429, and by the framework for the body-binding 400 and for 500:

{ "type": "https://tools.ietf.org/html/rfc9110#section-15.6.4", "title": "Too many requests.", "status": 429, "detail": "Request rate limit exceeded.", "code": "rate_limited" }

Note the content type: a strict application/json parser must accept application/problem+json too. The body-binding 400 adds an errors object (field → messages) and carries no code.

Codes carried by problem+json

The shared replay layer supplies the idempotency 409/413 codes below. The public end-customer POST .../internal-transfers and POST .../consolidate operations bypass it and use their own transactional recovery and JSON conflict codes; common header validation still applies. See Sub-customers & parent access.

Authentication codes are intentionally one per status: the granular reason (expired vs revoked vs IP-denied) is recorded in our audit trail and never returned, because it would tell a probe how far its guess got.

Idempotency retention and size boundary

Shared replay entries are retained for 24 hours. Except for the transactional commands above, on JSON requests the shared replay layer fingerprints bodies up to 1 MiB (1,048,576 bytes) — including chunked bodies, which are read through a bounded buffer rather than let through unprotected. A JSON body above that bound is refused with 413 idempotency_request_too_large before the operation runs. A successful response above the same 1 MiB boundary is not retained for byte-for-byte replay, so an identical retry is refused with 409 idempotency_response_unavailable instead of being re-executed while that completed entry remains retained. After expiry the shared replay layer can let the operation run again; payment workflows may have additional durable checks. A first attempt whose non-2xx failure is recorded does not lock the key — but only the identical bytes may retry it; a changed body under a failed key is refused with 409 idempotency_key_reused. The full contract is in Idempotency.

Operational response headers

• A valid X-Correlation-Id supplied by the caller is echoed in the response. If it is omitted, Kwiikpay supplies and returns one; it is on every response, including successes — include it in support requests.
• A 429 response uses Retry-After (whole seconds) to say when to retry.
• A 401 response carries WWW-Authenticate: Bearer.
• The API does not emit X-RateLimit-* headers. Do not build quota logic around them.

Policy-gate codes (flat ErrorResponse)

These are raised by shared gates rather than by one operation, on the money-moving routes (withdrawals, conversions, crypto withdrawals) and account opening.

A platform-wide money-movement pause is NOT reported with its own code on v1. The shared handler defines 409 money_movement_frozen, but the three v1 money routes catch it first and answer with their generic failure code (fiat_withdrawal_failed, crypto_withdrawal_failed, exchange_order_failed, shape 1) whose detail is operator-authored text. Treat those three codes as "retry later" unless detail says otherwise.

Operation codes (envelope, data.code)

Status is 422 unless marked 409. Every customer-scoped route also returns 404 (shape 2, code: null) for an unknown or unreachable customerId, and every money-moving route starts with the shared precondition 409 kyc_or_kyb_not_approved (the customer has not reached an approved verification status — read GET /customers/{customerId}/onboarding/status).

Customers and onboarding

Exchange (conversions)

Fiat accounts

Beneficiaries

Fiat withdrawals

Payout batches

A payout batch can be refused per item while the request returns 200 — inspect each item's status and failure_reason; see the operation.

Crypto

The two crypto operations also pass workflow decision codes through verbatim as 422 — the vocabulary is open and new codes ship without notice. Seen today on POST …/crypto/withdrawals: insufficient_funds, awaiting_crypto_delivery (bought but not yet delivered to the wallet — detail says how much you can send now), insufficient_network_funds, ledger_available_balance_insufficient, withdrawal_fee_unavailable, asset_network_policy_unavailable, crypto_withdrawals_disabled, crypto_withdrawal_below_minimum, provider_submission_failed. On POST …/crypto/wallets/{asset}/address: crypto_asset_network_policy_not_configured, crypto_deposits_disabled. A crypto withdrawal parked for review answers 202 with the normal withdrawal body and no code — 202 means "accepted for review", not "sent".

Practical guidance

• Branch on the HTTP status first, then on data.code (shape 1) or code (shapes 2 and 3). A null/missing code means "no machine reason — use the status."
• Accept application/problem+json as JSON.
• Treat unknown codes as a refusal that will not clear by resending the same request.
• Keep the X-Correlation-Id of every failed call in your logs.
• Paths under /api/v1/partner that do not appear in the reference are not supported and may answer with provider errors.