Error format
Failures that happen before a response starts use a normal HTTP status and a JSON body:
{
"code": "invalid_request",
"message": "Validation failed",
"requestId": "req_8f2c…",
"issues": [{ "path": "message", "message": "Too long" }]
}Quote requestId when you contact support: it finds the exact request. The issues array appears for validation errors.
| Status | Meaning |
|---|---|
400 | The request is invalid (invalid_request). Read issues. |
401 | Missing, malformed, expired or revoked key (unauthorized). |
402 | Credits are exhausted for this workspace. |
403 | The key is missing the scope this endpoint needs (forbidden). |
404 | Not found. Also returned for another workspace’s resources and for bots or documents this key may not use. |
413 | The upload is larger than your plan allows (file_too_large). |
415 | The file type is not supported (unsupported_file_type). Use PDF, DOCX, TXT, Markdown or CSV. |
429 | Rate limited or over quota (rate_limited). Retry-After says how many seconds to wait. |
500, 503 | A server-side problem or a provider outage. Idempotent reads are safe to retry. |
Streaming errors
POST /v1/chat answers 200 and then streams. If something fails after that point, the failure arrives as an error frame instead of a status code. Do not treat 200 as success: a chat is complete only when you receive done.
event: started
data: {"type":"started","conversationId":"c_…","messageId":"m_…","userMessageId":"m_…"}
event: token
data: {"type":"token","value":"You get "}
event: error
data: {"type":"error","code":"quota_exceeded","message":"The AI provider is temporarily rate-limited."}A streamed quota_exceeded can mean the AI provider is briefly unavailable rather than that your plan is used up, so read the message.
Rate limits
| Limit | Default |
|---|---|
Requests per key | 60 per minute |
Concurrent chat streams per key | 3 |
Concurrent searches per key | 8 |
Knowledge search per workspace | 300 per minute, 16 concurrent |
Chat stream deadline | 120 seconds |
Knowledge search deadline | 20 seconds |
Chat also has per-workspace and per-conversation limits on top of these. A closed connection releases its slot immediately.
Quotas and credits
Your plan sets a monthly allowance of messages and credits. Every accepted chat attempt counts, even if generation fails or you cancel, because the work was started. Requests rejected for ownership or validation reasons are not counted. A knowledge search reserves a provisional 0.25 credit before it runs and releases it if the request fails.
Retrying safely
Reads (GET) are safe to retry. Back off exponentially with jitter, and honour Retry-After on a 429. The SDK does this for you on reads and never on the calls above.