Errors

When something goes wrong, Qevron returns an appropriate HTTP status code and a descriptive JSON body.

Error format (OpenAI compatible)

{
  "error": {
    "message": "An error occurred while processing the request",
    "type": "qevron_error",
    "code": "model_not_found",
    "param": "model"
  }
}

Field	Description
error.message	Human-readable description
error.type	Error category (e.g. qevron_error, upstream_error)
error.code	Machine-readable code (e.g. model_not_found)
error.param	The parameter that caused the error (if any)

Some responses also include a qevron request-id field for tracing.

HTTP status codes

Code	Meaning	Typical cause
400	Bad Request	Invalid request format or missing field
401	Unauthorized	Missing/invalid API key
403	Forbidden	IP restriction, disabled group or insufficient balance
404	Not Found	Model or resource not found
429	Too Many Requests	Rate limit (RPM/TPM) exceeded
500	Internal Server Error	Server error
502	Bad Gateway	Upstream provider error
503	Service Unavailable	All channels exhausted / overloaded

Provider-specific error formats

Non-OpenAI endpoints use the corresponding provider's error format.

Anthropic (/v1/messages):

{ "type": "error", "error": { "type": "invalid_request_error", "message": "..." } }

Gemini (/v1beta/...):

{ "error": { "code": 400, "message": "...", "status": "INVALID_ARGUMENT" } }

Common errors

Symptom	Likely cause	Fix
401	Missing/wrong key	Is Authorization: Bearer sk-... correct?
404 model_not_found	Wrong model name or no access	List with /v1/models
429	Rate limit	Wait until the X-RateLimit-Reset-* time
403	Quota exhausted / IP block	Check your quota and IP restrictions

TIP

For retryable errors (429, 502, 503), retry after a short wait (exponential backoff). Qevron already retries automatically across channels.