Errors
Error codes, formats, and how to handle them.
Errors return JSON with a top-level error object: type, message, and code (HTTP status). Mid-stream failures use the same error object inside a terminal SSE event.
Error shape
{ "error": { "type": "insufficient_balance", "message": "External model included usage exhausted for this period. Enable on-demand usage or upgrade your plan.", "code": 402 }}Error catalog
| HTTP | type | When | Retry? |
|---|---|---|---|
| 400 | invalid_request | Bad JSON, missing fields, invalid message shape/role, unknown model, or a chat model sent to a dedicated endpoint | No — fix the request |
| 400 | invalid_request | "Model not available on your plan." — the model is blocked by your plan's server-side guardrail | No — pick another model |
| 400 | unsupported_dimensions | An embeddings request asked for a dimensionality the hosted model does not produce | No — use the native 384 dimensions |
| 401 | invalid_api_key | Missing, malformed, or revoked key | No — rotate key |
| 402 | insufficient_balance | Included Caedral or external pool exhausted without usable on-demand, inactive subscription, pending payment, or on-demand blocked after a failed card charge | No — upgrade or enable on-demand |
| 429 | rate_limit_exceeded | Per-key RPM exceeded (60 free-tier / 100 paid), the shared team bucket ran dry, or too many concurrent streams for the key | Yes — backoff |
| 502 | upstream_error | Model upstream failure. Messages are sanitized and truncated — internal provider detail is never echoed | Yes — limited |
| 500 | internal_error | Unexpected server error | Yes — limited |
Terminal SSE error events
data: {"error":{"message":"The model service stopped responding mid-stream. Please retry.","type":"upstream_error","code":502}} data: [DONE]Streaming requests return HTTP 200 before the first byte of model output, so anything failing after that point is delivered as a terminal data: error event followed by stream close. A failed stream releases its billing reservation — interrupted generations are not charged as completed ones.