Errors and Limits

Error format

All errors are returned inside an error object with:

• message
• type
• code
• request_id

Important HTTP status codes

Code	Typical meaning
400	invalid request
401	missing or invalid bearer token
403	access denied
404	resource or identifier not found
410	resource is no longer available
413	payload too large
429	rate or concurrency limit exceeded
502	provider or model execution error
503	service unavailable
504	provider or model execution timeout

Common validation errors

Typical examples include:

• model does not use the group:<uuid> or custom:<uuid> format
• messages is empty
• no user message is present
• temperature is outside the allowed range
• reasoning_effort uses an unsupported value
• metadata.mode is orch or synth with a custom:<uuid> target
• approval_id is missing during a resume request

Rate and concurrency limits

The API can reject requests with 429 when:

• too many calls are sent during a given time window
• too many simultaneous requests are open

Unless a deployment is configured differently, the default rate window allows 60 requests per 60 seconds. The default concurrency limits are 100 total open requests and 10 open requests for the same token.

A client should handle these cases with:

• controlled retries
• backoff
• client-side throttling

SSE error handling

In streaming mode, an error can happen after the stream has already started. The client should therefore:

1. inspect incoming events continuously
2. detect an error payload
3. log request_id
4. close the stream cleanly

Example SSE error event:

data: {"error":{"message":"Stream failed","type":"api_error","code":"stream_error","request_id":"req_123"}}

data: [DONE]

Size limits

Common limits include:

• JSON request body: 5 MB by default
• multipart file upload: 5 MB by default
• upload metadata field: 64 KB by default
• messages: 1 to 500 items
• max_tokens and max_completion_tokens: 1 to 200000

Good practices

• Always log request_id.
• Validate payloads before sending them.
• Avoid opening too many parallel streams with the same token.
• Treat tool_calls as a dedicated state, not as a regular text response.