Errors

Every Lazu error follows the OpenAI error envelope:

{
  "error": {
    "message": "Human-readable description",
    "type": "invalid_request_error",
    "code": "missing_required_parameter",
    "param": "purpose",
    "request_id": "req_lazu_01ABCDEF..."
  }
}

code is the stable machine-readable identifier — match on this, not on message. request_id is also returned as the X-Lazu-Request-Id HTTP header; include it when contacting support.

HTTP status codes at a glance

Status	Category	What to do
200	Success	-
201	Created (file upload)	Same as 200; some clients reject 201 — patch them
400	Bad request	Fix the request body / params; safe to retry after fix
401	Auth failed	Wrong / missing API key; do not retry without fixing key
403	Forbidden	Key disabled, IP not allow-listed, or quota exhausted
404	Not found	Wrong path, missing model, deleted file_id
413	Payload too large	Single file exceeds purpose's max size
422	Validation failed	Body matched schema but values invalid (e.g. temperature OOB)
429	Rate limit	Sleep `Retry-After` seconds, then retry
500	Lazu internal error	Retry with backoff; if persistent, open a ticket
502	Upstream bad gateway	Retry; Lazu will try another channel automatically once
503	Upstream unavailable	Retry with backoff; usually transient
504	Upstream timeout	Retry with backoff; check if your request is too slow

Common error codes

Auth

Code	When
`invalid_api_key`	Header missing, malformed, or key deleted
`insufficient_quota`	Balance hit zero — top up to continue
`ip_not_allowed`	Key has IP allowlist, your request came from outside it
`token_disabled`	Key was manually disabled in console
`token_expired`	Key passed its `expired_time`

Request shape

Code	When
`bad_request_body`	JSON didn't parse, or upstream rejected the request as malformed
`missing_required_parameter`	Required field absent (`param` shows which one)
`invalid_request`	Generic catch-all for malformed inputs
`model_not_found`	The model name doesn't exist or isn't accessible to this key
`convert_request_failed`	Internal: couldn't translate the request for the chosen vendor
`tokenization_error`	Couldn't count input tokens (rare; usually huge / malformed prompt)

Files API specific

Code	When
`purpose_not_supported`	Used `batch` / `fine-tune` / `assistants` (not supported yet)
`file_not_found`	`file_id` doesn't exist or wasn't uploaded by this key
`file_expired`	File aged past its 30-day retention
`file_too_large`	Single file over purpose's max size, or Responses dereference
	total exceeds 64 MB
`file_dereference_failed`	Couldn't pull the file from storage (very rare)

Pricing & quota

Code	When
`pricing_not_configured`	Model exists but no sell-price set in the requested lane
`pre_consume_token_quota_failed`	Token quota tracking conflict (retry once)

Rate limits

Code	When
`request_rate_limit_exceeded`	Hit your tier's RPM cap. `Retry-After` header shows seconds

Upstream / routing

Code	When
`upstream_error`	Upstream returned non-2xx. `details.status_code` has the original
`upstream_timeout`	Upstream didn't respond in time
`upstream_network_error`	Network failure connecting to upstream
`channel_response_time_exceeded`	Channel exceeded the per-channel timeout budget
`no_available_channel`	No channel is configured to serve the requested model+lane combo

Retry strategy

Roughly: retry idempotent error categories with exponential backoff:

Status / code	Retry?
`429 request_rate_limit_exceeded`	Yes — honor `Retry-After`
`500` / `502` / `503` / `504`	Yes — exp backoff, max 3 tries
`400` / `404` / `422`	No — fix the request
`401` / `403`	No — fix auth / quota first
`upstream_error` with 4xx underneath	No
`upstream_error` with 5xx underneath	Yes — exp backoff

Most popular OpenAI / Anthropic SDKs do this automatically. Don't disable their retry logic unless you have a strong reason.

Including a `request_id` in support tickets

Every Lazu response (success or error) includes:

X-Lazu-Request-Id: req_lazu_01KSBV4MC6THZ9TCZEM38KPYRX

Paste this into any support ticket. We can trace the full request path through routing, upstream call, and billing — far faster than re-creating the issue from a fuzzy description.