Errors & rate limits
/ The error shape, status codes, and rate limits shared across every endpoint.
Error shape
{ "error": "Human-readable message" }Status codes
| Status | Meaning | Retry? |
|---|---|---|
| 400 | Malformed request. Fix the body and resend | No |
| 401 | Missing or invalid credentials | No |
| 403 | Valid credentials, insufficient permission or plan | No |
| 404 | Agent not found | No |
| 413 | Payload too large (message over 4,000 chars) | No |
| 429 | Quota or rate limit exceeded | Yes, respect Retry-After |
| 500 | Unexpected server error | Yes, with backoff |
| 502 | Upstream model call failed | Yes, with backoff |
| 503 | Service temporarily unavailable or overloaded | Yes, with backoff |
Rate limits
Three sliding-window limits apply to chat and handoff-ticket requests, checked independently. A 429 response includes a Retry-After header, in seconds.
| Scope | Default limit | Window |
|---|---|---|
| Per IP | 30 requests | 60s |
| Per session | 20 requests | 60s |
| Per agent | 120 requests | 60s |