Error Handling

Request correlation

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

Gateway failures return JSON with stable machine-readable codes:

{
  "error": "budget_exceeded",
  "message": "Insufficient credits for Platform Access. Please top up your balance.",
  "code": "budget_exceeded"
}

Field	Description
`error`	Stable programmatic code
`message`	Human-readable detail
`code`	Legacy alias of `error` on some responses

Use error as the primary code in new integrations.

HTTP	Code	Meaning
`401`	`missing_api_key` / `invalid_api_key`	Fix Authorization header
`400`	`validation_error`	Fix request body
`400`	`guardrail_blocked`	Policy guardrail rejected input
`402` / budget family	`budget_exceeded`	Credits or plan limit
`503`	`all_providers_exhausted`	No eligible route for capability/profile

After SSE starts, terminal failures use:

event: error
data: {"error":"budget_exceeded","message":"...","code":"budget_exceeded"}

Read error programmatically; show message to users when appropriate
Retry idempotent requests on transient 5xx with backoff
Do not retry 401, 400, or budget errors without changing inputs or billing state

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