Every failure, typed and documented

No key was sent, or the key does not match an active key on any account.

details.reason separates the cases: missing_api_key when no credential was sent, invalid_api_key when the key was not recognised (including keys you have revoked or deleted), and query_string_key_rejected when a key arrived as ?api_key= — keys travel in the x-api-key header or as a Bearer token, never in the URL.

What to do · Send the key in the x-api-key header. Check it is intact: 46 characters beginning mn_. Retrying an unchanged request will not help.

Reserved. Part of the published error-type list, but not currently emitted.

A revoked key today answers 401 UNAUTHORIZED with details.reason = invalid_api_key. The type is listed here because it appears in the error-type roster served by /v1/utility/llms, and a defensive client should map it alongside UNAUTHORIZED.

What to do · Handle it exactly as you handle UNAUTHORIZED: stop retrying and surface a re-key prompt.

This key has an optional credit_limit and the call would push it past that cap.

details carries credit_limit and credits_used. The cap is reserved atomically before the wallet is touched, so it can also trigger mid-flight when several concurrent calls on one key race towards the same limit. Nothing is charged.

What to do · Raise the limit on the key, move the workload to another key, or let the budget do its job and stop the caller.

The key exceeded 600 requests in the last minute or 25 in flight, or invalid-key attempts were throttled.

The response carries a retry-after header and details.retry_after_seconds. A sliding-window rejection reports the seconds until the oldest request ages out; a concurrency rejection reports 1 second. Limits are per key, and batch items are admitted individually.

What to do · Wait for retry_after_seconds and retry. If you hit this constantly, spread the load or cap your own client-side concurrency below 25.

You reached the rolling 30-day fair-use ceiling on a metered endpoint.

Eligible endpoints using our metered commercial upstream share a per-account ceiling on upstream attempts per rolling 30 days; retries count. A refusal reports the limit and usage in details.limit and details.used. Quota-checked live responses report x-fairuse-limit and x-fairuse-remaining when available; cached responses may omit them. Missing headers do not mean unlimited quota. If the quota check is briefly degraded, a small shared temporary limit applies; if it is fully unavailable, these endpoints answer 503 until it recovers. Degraded refusals carry details.degraded, x-fairuse-degraded and retry-after. Nothing is charged for a refusal.

What to do · If you genuinely need this volume, contact us — sustained high-volume profile traffic is exactly what enterprise pricing is for, and the ceiling rises as our upstream rates improve.

Your account balance is below the cost of this call.

details carries required and remaining, and the envelope repeats the balance in credits_remaining. It can also surface after a concurrent-spend race even when the pre-flight check passed — in which case the request is refused honestly and charged 0.

What to do · Top up in the console. Zero-cost endpoints such as credits/balance and utility/* keep working at any balance, so you can always read your own state.

The endpoint exists, but the thing you asked it for does not — no such profile, post, repository or job.

This is a definitive answer, not a fault: the pipeline neither retries it nor falls back to another provider, because doing so would invent data for a genuine miss.

What to do · Check the identifier. Handle it as an ordinary empty result rather than an outage.

The request was understood but the parameters were not usable.

Endpoints answer 422 for a missing or blank required parameter, an unparseable URL or an out-of-range value; details usually names the field (for example { "missing": "handle" }). A parameter name the endpoint does not declare answers 400 before any cache lookup or charge, with details.unknown_parameters, details.accepted_parameters and, for a near miss, details.suggestions (for example { "handel": "handle" }); an empty undeclared value is treated as omitted. POST /v1/batch answers 400 for a malformed body or a list longer than 20 items, and 413 if its body exceeds the size limit. Idempotency conflicts use 409 while the original is in progress and 422 if the key is reused for different parameters.

What to do · Fix the request. GET /v1/utility/endpoint?id=platform/endpoint returns that endpoint’s exact parameter schema, free.

The source platform answered with something we could not turn into data.

Upstream 5xx responses are reported as 502. Some non-5xx upstream faults keep their own status — an exhausted upstream rate limit, for instance, reaches you as 429 with this type. Eligible retries and fallbacks may already have been attempted; deadlines, quota, configuration or spending limits can stop the chain earlier. A 503 with this type means something different: after repeated failures we take that upstream out of rotation for a short cooldown, so the request was refused immediately without calling it. That response carries a retry-after header, and like every error it costs 0 credits.

What to do · Retry with backoff, honouring retry-after when it is present. If it persists for one platform, check /v1/status for that platform’s error rate before assuming the fault is yours.

The source platform did not answer inside the adapter’s timeout on any attempt.

Every attempt — the first plus its retries — has to finish inside the adapter’s own request timeout. A timeout is treated as transient, but retries are bounded by the request deadline and available upstream budget.

What to do · Use bounded backoff. A returned UPSTREAM_TIMEOUT error has a net cost of 0, but a timeout in your client does not prove the server stopped. A later successful retry may be billed; use Idempotency-Key from the first direct request to protect ambiguous retries when the store is available.

The path is known, but no eligible real-data route can serve this request.

Distinct from ENDPOINT_NOT_FOUND on purpose: the path is real and planned, we simply cannot serve it with genuine data today. The production API will not answer it with sample data — realistic-looking JSON you could mistake for a result is worse than a clear refusal. Unwired-route refusals include a sandbox path in details; other eligibility refusals may not.

What to do · Call the same path under /sandbox to develop against a clearly-marked sample response, or GET /v1/utility/endpoints for registered operations and their metadata. The refusal costs 0 credits.

No endpoint answers that path, or the endpoint has been retired.

details carries the platform and endpoint as parsed from the URL, which is usually enough to spot a typo or a missing path segment. A retired endpoint answers 410 with this same type: details.reason is endpoint_removed, details.successor names the operation to call instead, and the versioning page explains the notice you had before it went.

What to do · Check the path against GET /v1/utility/endpoints — the registered catalogue, free to call.

Something went wrong on our side while processing the request.

The failure is logged against the request_id in the envelope, with no internal detail leaked into the response body. Nothing is charged.

What to do · Retry once. If it repeats, send the request_id to support — it is the fastest way to the exact log line.