Errors & rate limits

Error envelope

{
    "error": {
        "code": "insufficient_acu",
        "message": "Not enough ACU. Add usage capacity to continue.",
        "request_id": "req_..."
    }
}

Always log request_id and include it when contacting support.

Common codes

Rate limits

Every public request consumes both an organization-plan bucket and an API-key bucket. The effective limit is the lowest bucket that applies.

Enterprise overrides can raise the organization limit. A key can have a lower per-minute limit for isolation or safety.

Some route families add a tighter ceiling:

Every 429 includes Retry-After. Organization and key bucket failures use the stable rate_limited envelope and also include error.retry_after_seconds.

On 429:

1. Respect Retry-After.
2. Add jitter before retrying.
3. Do not retry an unbounded number of times.
4. Reduce request concurrency.

Cost controls

• Set per-key daily and monthly budgets.
• Use max_acu as the Agent's signed admission, billing, and downstream-call ceiling.
• Read active budget and usage context from GET /v1/account/usage.

Retry policy

Send an Idempotency-Key header on every POST. Repeating the same request with the same authenticated key replays its original response and bills once. Reusing that key for different credentials, scopes, route, query, body, content type, or response type returns 409 idempotency_conflict.

Validation failures (413 and 422) and 403 insufficient_scope do not consume the key, so the corrected request can reuse it. Explicitly retryable provider 5xx responses also release the key. API-key budget denials (daily_budget_exceeded and monthly_budget_exceeded) release the key so a retry can recheck a reset budget window. Successful responses and other deliberate responses—including credit/account 402 responses whose preflight may auto-recharge the workspace—consume the key and replay exactly, preventing duplicate side effects or charges.

• Retry 429 and transient 5xx responses with bounded exponential backoff.
• Do not automatically retry validation errors or missing permissions.
• For JSON Agent asks, poll the returned run instead of retrying the POST. For SSE, consume its terminal event.
• Treat a schema-constrained Agent failure as an error; do not reinterpret unvalidated prose as structured success.