Skip to main content

Error Formats

LLMLayer returns errors in two shapes, depending on where the request fails.

1. Structured Errors (most endpoint errors)

Endpoint-level failures return a structured envelope inside FastAPI’s detail field:

2. Plain-String Errors (account-level guards)

Account-level checks (API key, balance, rate limit) return a plain string in detail:
These occur before your request is processed, so they never incur any charge.

HTTP Status Codes


Error Types

The error_type field groups errors into categories:
Streaming endpoints (/answer_stream, /crawl_stream) deliver mid-stream failures as SSE frames of the form {"type": "error", "error": "..."} instead of HTTP error responses, because the HTTP status is already committed once streaming starts.

Automatic Refunds

You only pay when the work happens

The Extract API debits your selected modes up front, then automatically refunds the full amount if the request fails before any AI cost is incurred:Refunded errors say so explicitly: “You have not been charged for this request.”
Failures that happen after AI processing has started (e.g. an upstream model outage, or output_truncated when extracted JSON exceeds the size limit) are not refunded, because the model cost was already incurred.
Account-level rejections (401, 402, 423, 429) always happen before any charge.

SDK Exception Mapping

Both official SDKs raise typed exceptions so you can branch cleanly: All exceptions inherit from LLMLayerError, so except LLMLayerError / catch on the base class catches everything.

Common Error Codes by Endpoint


Need Help?

Discord Community

Chat with other developers

Email Support