Errors

Every error is returned as application/problem+json (RFC 9457) with an HTTP status, a stable machine code, and a request_id you can quote to support.

{
  "type": "https://developer.sodacards.com/errors/insufficient_balance",
  "title": "Insufficient balance",
  "status": 402,
  "detail": "Your wallet balance does not cover this order. Top up and try again.",
  "code": "insufficient_balance",
  "request_id": "req_9x8y7z"
}

Branch on code, not on title or detail: the status frames the category, the code names the exact reason, and several codes can share one status.

Common codes

Code	Status	Meaning
`invalid_request`	400	The request was malformed.
`invalid_api_key`	401	The key is missing, malformed, revoked or expired.
`forbidden`	403	The key lacks the scope for this action.
`insufficient_scope`	403	The key is not authorised for this endpoint.
`product_not_found`	404	The product does not exist or is not available to you.
`order_not_found`	404	The order is not yours or does not exist.
`order_rejected`	400	The order was not valid (product, quantity or inputs).
`order_amount_exceeded`	422	The order total is above the per-order maximum.
`insufficient_balance`	402	Your wallet does not cover the order.
`idempotency_key_missing`	400	A mutating request needs an `Idempotency-Key`.
`idempotency_key_reused`	422	The key was reused with a different body.
`request_in_progress`	409	A request with this key is still processing; retry shortly.
`order_not_ready`	409	Codes were requested before the order completed.
`codes_unavailable`	404	The completed order has no codes to reveal.
`reveal_rate_limited`	429	Codes for this order were revealed too often.
`rate_limited`	429	You exceeded the request rate for this key.

A 5xx never leaks internal detail: its code is always internal_error. Retry a 5xx after a short delay.

Get started

Core concepts

Webhooks

Common codes

​Common codes

Common codes