Skip to content
API · Errors

Error handling and HTTP codes

Uniform error response format and how to decide whether to retry.

Error response format

All error responses share the same JSON body regardless of the endpoint:

{
  "statusCode": 403,
  "message": "This token is missing the required scopes: orders:write",
  "error": "Forbidden"
}

For validation failures (422), message may be an array of strings, one per invalid field.

HTTP codes returned by the API

CodeMeaningRetry?
200Success.
201Resource created.
400Bad request or business rule violated (e.g. insufficient balance).No (fix first).
401Token missing, malformed, revoked or expired.No (regenerate token).
403Token valid but missing scope for the route.No (add scope).
404Resource not found in your store.No.
409Conflict (e.g. duplicate webhook URL).No.
422Validation failed (missing field, invalid format).No (fix the body).
429Rate limit exceeded (see rate limits).Yes, with backoff.
500Internal error.Yes, with exponential backoff.
502 / 503 / 504Service temporarily unavailable.Yes, with exponential backoff.

Recommended retry strategy

  • 4xx: do not retry. Fix the request first.
  • 429: honor the Retry-After header if present, otherwise exponential backoff starting at 1 s.
  • 5xx: exponential backoff — 1 s, 2 s, 4 s, 8 s, 16 s — max 5 attempts.
  • Use Idempotency-Key on order and recharge creates to avoid duplicates on retries.