Status codes
| Code | Means here |
|---|---|
| 400 | Malformed request — a body that fails validation |
| 401 | No credential, or one that is not recognised |
| 402 | Insufficient credits. Nothing ran and nothing was charged |
| 403 | Authenticated, but not permitted — no access to that organization or store, insufficient role, or a scope the credential does not carry |
| 404 | The resource does not exist |
| 409 | A state conflict — the resource is not in a state that allows this |
| 429 | Rate limited |
| 5xx | Ours. Retry with backoff |
403 comes before 404. A route resolves your access to the
organization or store first, so asking for a resource in a tenant you
cannot reach answers 403 whether or not the id exists. A 404 from an
authenticated call therefore means what it says: inside a tenant you can
reach, nothing has that id.
403 also covers two cases the body distinguishes: no access at all,
and access with an insufficient role. Read the error field rather than
inferring from the status.
402 means nothing streamed. A request whose estimated cost exceeds
your balance is refused before it runs. See
Credits & metering. You are never charged for a request
that was always going to run out. Top up or wait for the reset; retrying
immediately returns the same 402.
Rate limits
Ceilings are per endpoint and per actor, not a single global number. The actor is an IP address for public routes and the credential or user for authenticated ones — which is the practical reason to hold an Intelligence key rather than call anonymously: from a serverless platform your IP changes between invocations, and an IP-counted ceiling is unusable.
The ceilings themselves are operational, not a contract: they are
tuned against real load and can change. Treat a 429 as a signal to
back off, never as a value to hardcode.
What to do on 429
Exponential backoff with jitter. Start at a second, double, cap at a minute or so. Jitter matters more than the base: without it, everything you throttled retries at the same instant and you rebuild the spike that got you limited.
Do not retry a 402, a 403 or a 404: none of them become true by
being asked again.
When rate limiting cannot run
If the limiter's backing store is unreachable, guards do not refuse the request. This is a deliberate choice with a real trade-off: an outage in a counting service should not take the product down with it. Spend guards that once refused on a limiter failure were the reason it is written down here rather than left implicit.
Errors on the MCP server
MCP tool errors come back as tool errors, not HTTP failures: the transport succeeded, the tool refused. A tool your grant does not open is not registered at all, so it is absent from the tool list rather than present and failing. See MCP tools & scopes.