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’sdetail field:
2. Plain-String Errors (account-level guards)
Account-level checks (API key, balance, rate limit) return a plain string indetail:
HTTP Status Codes
Error Types
Theerror_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.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.
Recommended Retry Strategy
Common Error Codes by Endpoint
All endpoints
All endpoints
Extract API
Extract API
Scraper / PDF / Crawl / Map
Scraper / PDF / Crawl / Map
Answer API
Answer API
Need Help?
Discord Community
Chat with other developers
