Error Handling
The API uses conventional HTTP response codes to indicate the success or failure of requests. This page documents error formats and handling strategies.
Error Response Format
All error responses follow a consistent JSON structure:
{
"error": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"timestamp": "2026-07-10T12:00:00Z",
"path": "/api/v1/assets",
"details": [{ "field": "size", "message": "must be at most 100" }]
}| Field | Description |
|---|---|
| error | Machine-readable error code |
| message | Human-readable error description |
| timestamp | When the error occurred |
| path | The requested endpoint path |
| details | Additional details for validation errors (optional) |
HTTP Status Codes
| Code | Description |
|---|---|
| 400 | Invalid request parameters or malformed request body |
| 401 | Missing or invalid API key |
| 403 | API key doesn't have required permissions for this endpoint |
| 404 | Requested resource doesn't exist |
| 429 | Rate limit exceeded - retry after the specified time |
| 500 | Internal server error - please contact support if persists |
| 503 | Service temporarily unavailable - try again later |
Retry Strategy
For transient errors, implement a retry strategy with exponential backoff:
- For 429 errors, wait for the time specified in the X-RateLimit-Reset header before retrying
- For 5xx errors, use exponential backoff (1s, 2s, 4s, 8s...) with jitter
- Set a maximum retry count (e.g., 3-5 attempts) to avoid infinite loops
Rate Limiting
When you exceed the rate limit, the API returns a 429 status code with details about when you can retry:
Use the retryAfter field or X-RateLimit-Reset header to determine when to retry your request.
Validation Errors
For 400 errors, the response includes a details array with specific field-level errors:
Error Handling Best Practices
- Always check the HTTP status code before parsing the response body
- Implement exponential backoff for 429 and 5xx errors
- Log errors with the timestamp and path for debugging
- Handle specific error codes differently (e.g., 401 triggers re-authentication)