API Error Reference
Error Codes & Handling
Complete reference for API error codes, formats, and best practices for error handling.
Error Response Format
Error Response Example
{
"error": {
"type": "validation_error",
"code": "INVALID_FIELD",
"message": "The 'email' field must be a valid email address.",
"field": "email",
"request_id": "req_abc123xyz"
}
}HTTP Status Codes
400
Bad Request
The request is malformed or missing required parameters.
401
Unauthorized
Missing or invalid API key. Check your Authorization header.
403
Forbidden
Your API key doesn't have permission for this action.
404
Not Found
The requested resource doesn't exist.
409
Conflict
The resource already exists or is in a conflicting state.
422
Validation Error
One or more request fields failed validation.
429
Rate Limited
Too many requests. Check the retry_after header.
500
Server Error
An unexpected error occurred. Contact support if persistent.
Error Handling Best Practices
- Include request_id — Always log the request_id for debugging and support tickets.
- Implement retry logic — Retry 5xx errors with exponential backoff (max 3 attempts).
- Log errors properly — Log error type, code, message, and timestamp for debugging.
- User-friendly messages — Don't show raw API errors to users. Map them to friendly messages.
Need Help Debugging?
Check the API docs or contact our developer support team.