Envelope
Every response — success or error — comes back in the same envelope:
// success
{ "data": { ... } }
// error
{ "error": { "code": "FORBIDDEN", "message": "human-friendly message" } }HTTP status codes
| Code | Meaning | Retry? |
|---|---|---|
| 200 | OK | — |
| 201 | Created | — |
| 204 | No content (DELETE) | — |
| 400 | Bad request — payload failed validation | No — fix it |
| 401 | Missing or invalid token / API key | No — re-auth |
| 403 | Token valid but lacks permission | No |
| 404 | Resource not found | No |
| 409 | Conflict — e.g. idempotency replay with different payload | No — fix it |
| 422 | Validation passed but business rule rejected the request | No |
| 429 | Rate-limited — honour Retry-After | Yes, with backoff |
| 500–504 | Server problem on our side | Yes, with backoff + jitter |
Common error codes
UNAUTHORIZEDFORBIDDENNOT_FOUNDVALIDATION_ERRORIDEMPOTENCY_CONFLICTINSUFFICIENT_FUNDSWALLET_FROZENRATE_LIMITEDTOKEN_EXPIRED