Errors & rate limits

Handle stable public error envelopes, request IDs, rate limits, budgets, and versioning.

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

Code	Meaning
`missing_api_key`	No supported credential header was present
`invalid_api_key`	The credential is not recognized
`expired_api_key`	The credential has expired
`revoked_api_key`	The credential has been revoked
`insufficient_scope`	The key lacks the endpoint's required scope
`active_account_required`	The workspace cannot currently use the API
`insufficient_acu`	The workspace has insufficient usage capacity
`daily_budget_exceeded`	The active key reached its daily budget
`monthly_budget_exceeded`	The active key reached its monthly budget
`rate_limited`	An organization or key rate bucket was exceeded
`query_required`	A search or Agent prompt was missing
`identity_required`	The endpoint needs a stronger identity anchor

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.

Plan	Organization limit
Free	10 requests/minute
Pay as you go	30 requests/minute
API Pro, Starter, or Pro	300 requests/minute
Scale or Teams	1,000 requests/minute

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:

Route family	Per minute	Per hour
`POST /v1/search`	30	300
`/v1/socials`	60	600
`/v1/linkedin/*`	60	600

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:

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

Cost controls

Set per-key daily and monthly budgets.
Use max_acu as an Agent admission and billing limit. It is not a provider compute ceiling.
Read active budget and usage context from GET /v1/account/usage.

Retry policy

Retry 429 and transient 5xx responses with bounded exponential backoff.
Do not automatically retry validation errors or missing permissions.
Do not blindly retry a long Agent request after an ambiguous disconnect; use SSE and consume its terminal event.
Treat a schema-constrained Agent failure as an error; do not reinterpret unvalidated prose as structured success.