Error Response Format
{
"error": {
"code": "string",
"message": "Human-readable description",
"trace_id": "trc_abc123",
"details": [
{
"field": "amount",
"issue": "must be a positive integer"
}
]
}
}
Authentication Errors (401 / 403)
| Code |
HTTP |
Description |
Resolution |
| TOKEN_EXPIRED |
401 |
Access token has expired |
Request a new access token |
| TOKEN_INVALID |
401 |
Token signature does not match |
Check that you are using the correct signing key |
| TOKEN_MISSING |
401 |
No Authorization header provided |
Add Authorization: Bearer {token} |
| SCOPE_INSUFFICIENT |
403 |
Token lacks required scope |
Re-authenticate with the required scope |
| IP_NOT_ALLOWED |
403 |
Request originates from a blocked IP |
Add your IP to the allowlist |
Request Errors (400 / 422)
| Code |
HTTP |
Description |
| INVALID_PARAMETER |
400 |
A query parameter has an invalid value |
| MISSING_REQUIRED_FIELD |
400 |
A required JSON field is absent |
| VALIDATION_FAILED |
422 |
One or more fields failed validation rules |
| DUPLICATE_IDEMPOTENCY_KEY |
409 |
This idempotency key was already used |
Resource Errors (404 / 409)
| Code |
HTTP |
Description |
| RESOURCE_NOT_FOUND |
404 |
The requested resource does not exist |
| ACCOUNT_CLOSED |
409 |
Operation attempted on a closed account |
| INSUFFICIENT_FUNDS |
409 |
Account balance is too low |
Rate Limit / Server Errors
| Code |
HTTP |
Description |
| RATE_LIMIT_EXCEEDED |
429 |
Too many requests — check Retry-After header |
| INTERNAL_SERVER_ERROR |
500 |
Unexpected error — retry with back-off |
| SERVICE_UNAVAILABLE |
503 |
Temporary outage — retry later |
