Error codes

primerouter error responses are isomorphic with OpenAI's for drop-in compatibility.

Standard error format

{
  "error": {
    "type": "invalid_request_error",
    "message": "Model 'qwen-max-x' not found",
    "code": "model_not_found",
    "param": "model"
  }
}

Common HTTP status

Status	type	Meaning	Suggested handling
400	invalid_request_error	Malformed request / unknown model / bad param	Check model, JSON schema
401	authentication_error	Key invalid / expired / missing	Check Authorization header
402	insufficient_quota	Out of quota	Top up or grant more
403	permission_denied	Key valid but no access (model / IP / group)	Adjust key settings
404	not_found_error	Endpoint doesn't exist	Check URL
429	rate_limit_exceeded	Rate limited	Read Retry-After, exponential backoff
500	api_error	primerouter internal error	Retry 1–2 times
502 / 503	upstream_error	Upstream unavailable	primerouter already attempted failover; if you still see 503 all candidates failed
504	timeout_error	Upstream response timeout	Retry

Rate-limit details

429 responses include:

Retry-After: 30
X-RateLimit-Limit-Requests: 60
X-RateLimit-Remaining-Requests: 0
X-RateLimit-Reset-Requests: 30s
X-RateLimit-Limit-Tokens: 60000
X-RateLimit-Remaining-Tokens: 0
X-RateLimit-Reset-Tokens: 60s

Use Retry-After; add jitter to avoid thundering herd.

Upstream error pass-through

When upstream returns 4xx/5xx, primerouter:

1. Tries the next candidate channel (if any)
2. After all fail, passes through the last upstream error verbatim (preserving code, message)
3. Adds x-upstream-attempts: <n> header

trace_id

Every response includes:

X-Request-Id: 01J9XQH3M8K4N5P6Q7R8S9T0V1

When reporting issues, this ID lets us locate your call in Logs.

Localization

Error message is in English by default. To get other languages:

Accept-Language: zh-CN

7 languages supported, matching product i18n.

Full code table

For granular code semantics, see each endpoint's responses section in API Reference.