application/problem+json. The HTTP status frames the category; the machine code names the exact reason and is the stable value your code should branch on.
The error body is snake_case (
request_id, not requestId), unlike the camelCase business responses. The set of codes is open: branch on the codes you know and fall back to the HTTP status for any you do not. A type link to a code this page does not list still lands here.Testing error paths
With a test key, force a specific failure deterministically by sending theX-Test-Scenario header set to one of insufficient_balance, order_rejected or order_amount_exceeded, instead of waiting for the condition to occur. A live key that carries the header is refused with test_scenario_not_allowed.
Authentication and access
api_key_required
401 — No API key was provided. Send it in the X-API-Key header or as a Bearer token.
invalid_api_key
401 — The API key is missing, malformed, revoked or expired.
ip_not_allowed
403 — This key may not be used from your address. Check the key’s IP allowlist.
insufficient_scope
403 — This key does not have the scope required for this action.
forbidden
403 — This key may not perform this action.
reseller_not_approved
403 — This account is not an approved reseller.
test_scenario_not_allowed
400 — The X-Test-Scenario header is only honored for a test key.
Rate limiting
rate_limited
429 — You have exceeded the request rate for this key. Retry after the delay in Retry-After. See Rate limits.
reveal_rate_limited
429 — Codes for this order have been revealed too often. Retry after a short delay.
Request validation
invalid_request
400 — The request was not valid. Check the parameters and try again.
malformed_identifier
400 — An identifier in your request is not a valid UUID. Check the id and try again. A well-formed id that does not exist is a 404, not this.
invalid_cursor
400 — The pagination cursor is not valid. See Pagination.
not_found
404 — The requested resource does not exist.
product_not_found
404 — The requested product does not exist or is not available to you.
Idempotency
idempotency_key_missing
400 — This request requires an Idempotency-Key header. See Idempotency.
idempotency_key_reused
422 — This Idempotency-Key was already used for a request with a different body.
request_in_progress
409 — A request with this Idempotency-Key is still being processed. Retry after a short delay.
Orders
order_rejected
400 — The order could not be placed. Check the products, quantities and input fields.
insufficient_balance
402 — Your wallet balance does not cover this order. Top up and try again.
order_amount_exceeded
422 — The order total exceeds the maximum allowed for a single order.
order_not_found
404 — The requested order does not exist.
order_not_ready
409 — The order is still being fulfilled. Poll the order and retry when it is completed.
codes_unavailable
422 — This order has no codes to reveal.
Webhooks
invalid_webhook_url
400 — The webhook URL is not a valid absolute URL.
webhook_url_not_https
400 — A webhook URL must use https.
webhook_url_not_public
400 — A webhook URL must point at a publicly routable address.
invalid_webhook_events
400 — Subscribe to at least one known event type.
webhook_not_found
404 — The requested webhook endpoint does not exist.
webhooks_unavailable
503 — Webhook registration is not configured on this service.
Service
unavailable
503 — The service is temporarily unavailable. Retry after a short delay.
internal_error
500 — Something went wrong on our side. The cause is never leaked in the body; quote the request_id when you contact support.