Error code reference

This is the canonical, searchable list of every code value the QairoPay API can return inside an error response. Use the filter to jump to one, or browse by section. Every code links back to the relevant guide page for fuller context.

For the shape of the error envelope (type, code, message, param, request_id, docs_url) see Errors.

invalid_parameter400Request body or query failed validation.

Retryability: not retryable without code changes.

Common codes:

• missing_field — required field absent. param identifies which.
• unknown_field — field not recognized for this endpoint and API version.
• type_mismatch — field had the wrong JSON type (e.g. string where number expected).
• out_of_range — value below minimum or above maximum (e.g. limit > 100).
• too_long / too_short — string length violated bounds.
• pattern_mismatch — string failed a regex constraint (e.g. Idempotency-Key contains illegal characters).
• invalid_enum — value not in the allowed set; the schema lists what is.
• invalid_currency — currency code not supported by this program.
• invalid_country — ISO 3166-1 alpha-2 code unsupported by the program.

How to recover: read error.param, fix the field, retry. Generate a new Idempotency-Key only if you changed the body.

unauthenticated401No key, malformed key, or the key is no longer valid.

Retryability: not retryable without fixing auth.

Common codes:

• missing_auth — no Authorization header.
• invalid_key — key not recognized (typo, deleted, never existed).
• revoked_key — key was revoked from the dashboard.
• expired_token — OAuth access token past its TTL. Refresh it.
• scoped_to_other_env — sandbox key used against live, or vice versa.
• malformed_authorization — header present but not a recognizable format.

How to recover: verify the key prefix, confirm it’s active in the dashboard, and ensure the request is hitting the matching base URL.

insufficient_scope403Key authentic but lacks the required role or scope.

Retryability: not retryable; needs a key with the right scope or a fresh second factor.

Common codes:

• read_only_key — write attempted with a read-scoped key.
• write_required / admin_required — operation needs a higher role than your key carries.
• factor_required — admin operation requires a fresh second factor in the same request. The response includes a one-time MFA challenge URL.

not_found404Resource doesn’t exist in this tenant.

Retryability: not retryable.

Note: cross-tenant access returns 404, not 403 — we don’t tell you whether a record exists in another tenant.

idempotency_conflict409Same Idempotency-Key reused with a different request body.

Retryability: generate a new key. See Idempotency.

idempotency_inflight409A request with this key is still being processed.

Retryability: retry after retry_after_ms milliseconds (exponential backoff on subsequent retries). The SDK handles this for you.

conflict409Resource state precludes the operation.

Retryability: not retryable without re-reading the resource.

Common codes:

• already_revoked — pass already revoked; the operation is a no-op.
• already_terminated — card already terminated.
• cannot_modify — generic state guard (e.g. trying to update an archived template).

rate_limited429Exceeded the rate limit for this bucket.

Retryability: honor the Retry-After header. The SDK retries automatically.

Common codes:

• tenant_limit — your tenant hit its per-bucket window.
• endpoint_limit — a specific endpoint’s limit, not the tenant aggregate.
• burst_exhausted — token-bucket burst budget used up.

See Rate limits.

validation_failed422Business or compliance rule rejected the operation.

Retryability: depends on the code. Some are terminal (sanctions hits); others resolve after manual review.

Common codes:

• kyb_rejected — tenant onboarding rejected. Cannot issue in live.
• kyc_rejected — cardholder identity verification rejected.
• sanctions_hit — counterparty appears on a sanctions list. Terminal.
• aml_review_required — flagged for manual review; the case will resolve out-of-band.
• cardholder_blocked — cardholder is frozen pending review.
• program_not_active — KYB approved but the program hasn’t been activated. Listen for program.activated.
• state_mtl_required — issuance to this U.S. state requires an MTL not yet in place. Live only.

card_declined402Card-network decline. The code is the specific decline reason.

Retryability: depends on the reason — some are user-correctable (insufficient funds, expired card), some are terminal (stolen card, sanctions).

User-correctable codes (retry is OK after user action):

• insufficient_funds — balance too low. Top up.
• incorrect_pin — PIN didn’t match.
• expired_card — card past its expiration date.
• spending_control_breach — your own spending control denied it. Adjust controls if intentional.

Terminal decline codes (do not retry):

• stolen_card, lost_card, pickup_card — network flagged the card. Issue a new one.
• restricted_card — card barred from this merchant or category.
• pin_try_exceeded — too many wrong-PIN attempts. Requires unblocking via the issuing bank.
• cardholder_blocked — compliance freeze on the cardholder.

Transient decline codes (retry sometimes works):

• issuer_unavailable — sponsor bank or processor briefly unavailable.
• network_error — card network responded with a generic error.
• do_not_honor — network heuristics flagged the txn. Often resolves on retry; surface to the user with a “please try again” message.

provider_error502An upstream provider returned an error.

Retryability: retry with exponential backoff. The SDK does this automatically up to 3 attempts.

Common codes (provider identified in code or message):

• stripe_error — billing-side problem.
• persona_error — KYC partner unavailable.
• bridge_error — on-ramp leg failed; the settlement enters manual_review.
• sponsor_bank_error — card-network partner unavailable.
• aptos_network_error — Aptos congestion or transient validator issue.

internal_error500We dropped the ball. The fix is on our side.

Retryability: retry with exponential backoff. Email developers@qairopay.com with the request_id if it persists.

service_unavailable503Maintenance or transient overload.

Retryability: honor Retry-After. Subscribe to status for outage notifications.