Skip to content
OrbContext
19 pages

API reference

Errors & limits

Error shapes, rate limits, quotas, retries and credits.

Error format

Failures that happen before a response starts use a normal HTTP status and a JSON body:

JSON
{
  "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.

StatusMeaning
400The request is invalid (invalid_request). Read issues.
401Missing, malformed, expired or revoked key (unauthorized).
402Credits are exhausted for this workspace.
403The key is missing the scope this endpoint needs (forbidden).
404Not found. Also returned for another workspace’s resources and for bots or documents this key may not use.
413The upload is larger than your plan allows (file_too_large).
415The file type is not supported (unsupported_file_type). Use PDF, DOCX, TXT, Markdown or CSV.
429Rate limited or over quota (rate_limited). Retry-After says how many seconds to wait.
500, 503A 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.

HTTP
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

LimitDefault
Requests per key60 per minute
Concurrent chat streams per key3
Concurrent searches per key8
Knowledge search per workspace300 per minute, 16 concurrent
Chat stream deadline120 seconds
Knowledge search deadline20 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.