HTTP Status Codes
Client Error Codes (4xx)
| Code | Name | Description | Common Causes |
|---|---|---|---|
| 400 | Bad Request | Malformed request syntax or invalid request parameters. | Invalid JSON, missing required parameters, malformed data |
| 401 | Unauthorized | Authentication required. API key missing, invalid, or revoked. | Missing Authorization header, invalid API key, revoked key |
| 403 | Forbidden | Authentication succeeded, but insufficient permissions for this resource. | API key lacks permissions, accessing another org’s resources |
| 404 | Not Found | Requested resource does not exist or was not found. | Invalid resource ID, resource deleted, typo in URL |
| 405 | Method Not Allowed | HTTP method not supported for this endpoint (e.g., POST on a GET-only route). | Using wrong HTTP method (POST instead of GET) |
| 409 | Conflict | Request conflicts with current resource state (e.g., duplicate record). | Duplicate resource, race condition, resource locked |
| 422 | Unprocessable Entity | Request syntax valid, but semantic errors in data (validation failures). | Missing required fields, invalid data types, values out of range |
| 429 | Too Many Requests | Rate limit exceeded. Wait before making additional requests. | Too many requests in short period, see Rate Limits |
Server Error Codes (5xx)
| Code | Name | Description | What To Do |
|---|---|---|---|
| 500 | Internal Server Error | Unexpected error on the server. Contact support if issue persists. | Retry with exponential backoff |
| 502 | Bad Gateway | Invalid response from upstream server. Usually temporary. | Retry after brief delay |
| 503 | Service Unavailable | Server temporarily unavailable (maintenance or overload). | Retry after delay, check status page |
| 504 | Gateway Timeout | Request timed out waiting for upstream server. | Retry with exponential backoff |
Validation Errors
When a request fails validation (422 status), the response includes anerrors object with field-specific messages:
{
"message": "The given data was invalid.",
"errors": {
"email": ["The email field is required.", "The email must be a valid email address."],
"amount": ["The amount must be greater than 0."]
}
}