Error Reference

Non-success responses use a structured envelope:

{
  "error": {
    "code": "UPSTREAM_ERROR",
    "category": "upstream",
    "message": "Underlying provider returned an error.",
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "request_id": "req_abc123",
    "retryable": true,
    "suggested_action": "retry_with_backoff"
  }
}

Top-level code, message, and request_id are also present for older SDKs. New integrations should read error.code and error.category.

Categories

Codes

Oversized uploads and queue payloads are rejected with the structured envelope (413 for streamed uploads); reduce the payload instead of retrying — see Rate limits.

Backoff guidance

For quota, upstream, routing, and gateway retryable errors, use jittered exponential backoff and cap retries. For model_output, a retry can help, but repeated failures usually mean the prompt, tool_choice, or max_tokens needs to change.

What LatentKit retries for you

Inside a single request, LatentKit only auto-retries transport failures that provably happen before the request reaches the provider (connection establishment). Ambiguous failures — read timeouts and protocol errors after the provider may have accepted the request — are never replayed automatically, because the provider might already have run and billed the generation. They surface as UPSTREAM_TIMEOUT or UPSTREAM_ERROR so your application decides whether a replay is safe.

Route-level failover is separate: when an attempt fails with a retryable provider error, the published policy's next eligible provider/model entry is tried, and you still receive one response.

An unknown purpose is not an error

A purpose that is not configured, is disabled, or cannot serve the endpoint's capability does not produce an error. The request runs on the app's assigned route and returns 200. This is deliberate: shipping application code that names a purpose before someone configures it in the console must not take the feature down.

Detect it on the response rather than in an error handler:

A malformed purpose is a different case and does fail loudly:

So a typo in your code is a hard error, while a missing console binding is a soft fallback. Log lk_applied_purpose in production; the console also charts degradations per purpose on the app's analytics.

Debugging with request IDs

Every response should include X-LK-Request-ID; JSON bodies also include error.request_id. Include that ID when contacting support or correlating your app logs with LatentKit request logs.