Error Handling

Understanding error responses and how to handle them in your applications.

Error Response Format

All error responses follow a consistent structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "specific_field",
      "issue": "specific issue description"
    }
  },
  "meta": {
    "timestamp": "2024-01-01T00:00:00Z",
    "requestId": "req_1234567890",
    "version": "v1"
  }
}

HTTP Status Codes

400 Bad Request

Invalid request parameters or malformed request body.

401 Unauthorized

Missing or invalid API key.

403 Forbidden

Valid API key but insufficient permissions for the requested resource.

404 Not Found

Requested resource does not exist.

429 Too Many Requests

Rate limit exceeded. Check rate limit headers for retry information.

500 Internal Server Error

Server-side error. Contact support if this persists.

Error Codes

• INVALID_REQUEST - Request parameters are invalid
• UNAUTHORIZED - Authentication failed
• FORBIDDEN - Insufficient permissions
• NOT_FOUND - Resource not found
• RATE_LIMITED - Rate limit exceeded
• USAGE_LIMIT_EXCEEDED - Monthly usage limit exceeded
• INTERNAL_ERROR - Server error