Errors

The API uses conventional HTTP status codes and returns errors in a consistent JSON format.

Error response format

All errors follow this structure:

{
  "error": {
    "type": "authentication_error",
    "message": "A human-readable description of the error.",
    "code": "key_invalid",
    "request_id": "abc123-def456"
  }
}

Field	Type	Description
type	string	The category of error (see below)
message	string	A human-readable explanation
code	string	A machine-readable error code
request_id	string	The request ID for debugging (matches X-Request-Id header)
param	string	(optional) The parameter that caused the error
errors	array	(optional) Detailed validation errors

Error types

Type	HTTP Status	Description
authentication_error	401	Missing or invalid API key
authorization_error	403	Key lacks required scope
invalid_request_error	400	Malformed request
not_found_error	404	Resource not found
validation_error	422	Request failed validation
conflict_error	409	Resource conflict
rate_limit_error	429	Rate limit exceeded
api_error	500	Internal server error

Common error codes

Authentication errors (401)

key_missing — No API key provided.

{
  "error": {
    "type": "authentication_error",
    "message": "API key is missing. Include it in the Authorization header as: Bearer <your-key>",
    "code": "key_missing"
  }
}

key_invalid — The API key doesn’t match any active key.

{
  "error": {
    "type": "authentication_error",
    "message": "The provided API key is not valid.",
    "code": "key_invalid"
  }
}

key_expired — The API key has been revoked or expired.

{
  "error": {
    "type": "authentication_error",
    "message": "This API key has been revoked or has expired.",
    "code": "key_expired"
  }
}

Authorization errors (403)

scope_insufficient — The API key doesn’t have the required scope.

{
  "error": {
    "type": "authorization_error",
    "message": "Your API key does not have the required scope for this endpoint.",
    "code": "scope_insufficient"
  }
}

Rate limit errors (429)

rate_limited — Too many requests.

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Please retry after the Retry-After period.",
    "code": "rate_limited"
  }
}