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. Idempotency-Key conflict → 409 idempotency_key_reused / idempotency_key_in_progress
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 (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

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

Idempotency entries are retained for 24 hours. The shared replay layer hashes known-length JSON request bodies up to 1 MiB (1,048,576 bytes). A chunked request with no known content length, or a request above that size, currently proceeds without middleware replay protection. A successful response above the same 1 MiB boundary is not stored for byte-for-byte replay. A first attempt that returns any non-2xx does not lock the key. 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.