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
| Code | Meaning | Retry? |
|---|---|---|
200 | Success. | — |
201 | Resource created. | — |
400 | Bad request or business rule violated (e.g. insufficient balance). | No (fix first). |
401 | Token missing, malformed, revoked or expired. | No (regenerate token). |
403 | Token valid but missing scope for the route. | No (add scope). |
404 | Resource not found in your store. | No. |
409 | Conflict (e.g. duplicate webhook URL). | No. |
422 | Validation failed (missing field, invalid format). | No (fix the body). |
429 | Rate limit exceeded (see rate limits). | Yes, with backoff. |
500 | Internal error. | Yes, with exponential backoff. |
502 / 503 / 504 | Service temporarily unavailable. | Yes, with exponential backoff. |
Recommended retry strategy
- 4xx: do not retry. Fix the request first.
- 429: honor the
Retry-Afterheader 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.