Limits, Errors and Quotas
All Cells API responses follow a consistent error shape. Quota and rate-limit errors carry machine-readable codes so your integration can respond to them without string-parsing.
Error shape
Every error response has a JSON body with a success: false flag and an error string. Quota and limit errors additionally include a codefield.
| HTTP status | code | Meaning |
|---|---|---|
400 | (none) | Invalid request body or parameters. Fix the request and retry. |
401 | (none) | Missing or invalid API key or bearer token. |
402 | SMALL_HOURS_EXHAUSTED | Monthly Small-hours allowance is exhausted. Upgrade or wait for the next cycle. |
403 | (none) | Authenticated but not authorized for this project or feature (e.g. alwaysOn on a plan that does not support it). |
404 | (none) | Session or resource not found, or belongs to a different org/project. |
409 | (none) | Session is not in a valid state for this operation (e.g. trying to resume a session that is already running). |
429 | CONCURRENT_LIMIT_REACHED | Too many concurrent sessions for this plan. Wait for a session to end, then retry. |
503 | (none) | The session could not be created due to an infrastructure error. Retry with exponential backoff. |
Rate limits
| Endpoint group | Limit |
|---|---|
| Session creation | Plan-dependent concurrent cap; per-org rate limit applies |
| File writes | 120 requests per minute per org |
| File reads | 60 requests per minute per org |
| Services, service logs, expose | 120 requests per minute per org |
| SSE log streams (concurrent) | 10 concurrent open streams per org |
Note
The
X-Cells-Quota-Warning response header is set (with an integer percent value) when your monthly Small-hours usage is between 80 and 99 percent. Surface this to users before they hit the 402 wall.File limits
- Write: max 200 files per request, about 9 MB of file content per write (either encoding); split larger files across multiple writes.
- Read: max 10 MB per file.
Command limits
timeoutMs: max 300,000ms (300 seconds).initialExec.timeoutMs: max 120,000ms (2 minutes).- Combo sessions: max 4 languages per combo.