Errors

Errors use a consistent JSON envelope with a stable type and code.

json

{
  "error": {
    "message": "Token quota exceeded. Used 5,000,000 of 5,000,000 for this month.",
    "type": "quota_error",
    "code": "quota_exceeded",
    "request_id": "req_abc123"
  }
}

Status codes

Status	Type	Meaning
400	invalid_request_error	Malformed request or failed validation.
401	authentication_error	Missing, invalid, or expired API key.
403	authorization_error	Insufficient scope or model not in your plan.
404	invalid_request_error	Model not found or endpoint not enabled.
413	invalid_request_error	Request body too large.
429	rate_limit_error / quota_error	Rate limit or token quota exceeded.
502	provider_error	Upstream provider unavailable (after failover).
504	provider_error	Upstream provider timed out.
500	server_error	Unexpected internal error.

Request IDs

Every response includes an x-request-id header, also present as request_id in error bodies. Include it when reporting an issue — it lets us trace the request.