Errors

The API uses standard HTTP status codes to indicate success or failure of requests.

Status Codes

Error Response Format

All error responses follow this format:

{
  "error": "Error message describing what went wrong"
}

Common Error Scenarios

400 Bad Request

Returned when request parameters or body are invalid:

{
  "error": "Invalid date range: startDate must be before endDate"
}

401 Unauthorized

Returned when the API key is missing or invalid:

{
  "error": "Unauthorized - Invalid or missing API key"
}

429 Too Many Requests

Returned when rate limits or quotas are exceeded. The response includes details about which limits were exceeded:

{
  "error": "Rate limit exceeded",
  "rateLimits": [
    {
      "id": "rl_123",
      "name": "API Rate Limit",
      "limit": 100,
      "remaining": 0,
      "reset": 1704067200
    }
  ]
}

The response also includes standard rate limit headers:

• X-RateLimit-Limit: Maximum requests allowed
• X-RateLimit-Remaining: Requests remaining in current window
• X-RateLimit-Reset: Unix timestamp when window resets
• Retry-After: Seconds to wait before retrying