Error Handling

Request correlation

Every response should include X-LK-Request-ID. Log it with failures when opening support tickets or tracing logs.

Typed JSON errors

Gateway failures return a structured JSON envelope with stable machine-readable codes:

{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "category": "billing",
    "message": "Insufficient credits for Platform Access. Please top up your balance.",
    "request_id": "req_abc123",
    "retryable": false
  }
}

Field	Description
`error.code`	Stable programmatic code
`error.category`	Broad handling category such as `upstream`, `model_output`, `auth`, or `billing`
`error.message`	Human-readable detail
`error.request_id`	Correlation ID for request logs and support
`error.retryable`	Whether retrying the same request can reasonably succeed

Top-level code, message, and request_id remain for older SDKs. New integrations should use error.code and error.category.

Common codes

HTTP	Code	Meaning
`401`	`INVALID_API_KEY`	Fix Authorization header
`400` / `422`	`VALIDATION_ERROR`	Fix request body
`403`	`POLICY_REJECTED`	Policy guardrail or route eligibility rejected input
`402`	`INSUFFICIENT_CREDITS`	Credits or plan limit
`429`	`RATE_LIMITED`	Retry with backoff
`503`	`NO_HEALTHY_PROVIDER`	No eligible healthy route for capability/profile
`200` / `503`	`TOOL_CALL_NOT_PRODUCED`	A tool call was required, but the model returned text

Streaming errors

After SSE starts, terminal failures use:

event: error
data: {"error":{"code":"UPSTREAM_ERROR","category":"upstream","message":"...","request_id":"req_abc123","retryable":true},"code":"UPSTREAM_ERROR"}

Client guidance

Read error.category for generic handling and error.code for precise handling
Retry idempotent requests on transient 5xx with backoff
Do not retry 401, 400, or budget errors without changing inputs or billing state

Upgrade-oriented errors

Some plan-limit responses include fields like upgrade_required and upgrade_to for console-native upgrade flows.

See Error reference for the complete taxonomy and retry guidance.