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 or account reached its plan’s request or concurrency limit. Starter key limits begin at 600/minute and 50 in flight; higher paid tiers increase both. Free accounts share 600/minute and 50 in flight across keys. Invalid-key attempts can also be 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. Check the scope and effective headroom headers. Batch items are admitted individually.

What to do · Wait for retry_after_seconds and retry. Pace requests below the rate and concurrency ceilings reported in the response headers. Check the rate-limit guide for your plan’s key and account limits.

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 · Wait for your allowance to reset, or upgrade your plan in Billing. 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 · 400, 413 and 422 INVALID_PARAMETERS responses include error.retryable = false: fix the request before trying again. Follow details.guidance for a correction and example. GET /v1/utility/endpoint?id=platform/endpoint returns that endpoint’s exact parameter schema, free. A 409 in-progress conflict still requires waiting for the original request. Absence of retryable is not permission to retry every error.

The requested website refused access to its content.

A publisher HTTP 401 or 403 is a target access refusal. Your Monocrawl API key may still be valid. The message preserves the publisher status, and the failed extraction costs zero credits.

What to do · Use an accessible source URL. Repeating the same request does not resolve a publisher access restriction.

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

Upstream 5xx responses are reported as 502. Some upstream faults keep their own status, such as 429 for an upstream rate limit. Eligible retries and fallbacks may already have been attempted. A 503 may mean a circuit cooldown, exhausted source quota or no currently eligible source; details.reason distinguishes these cases. Only circuit cooldowns promise recovery after a short retry-after delay. Confirmed uncharged or refunded failures report zero; an unresolved accounting outcome can report credits_used:null and billing_status:pending_reconciliation.

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.

Free data-access capacity is unavailable, or this account reached its daily Free allowance.

For a daily allowance, details.reason is daily_budget, details.scope is account and details.resets_at gives midnight UTC. The retry-after header gives the remaining wait. Active subscriptions, including complimentary subscriptions, are exempt from this Free daily budget. Other Free capacity protections may use shorter retry delays.

What to do · Honor retry-after. A daily allowance will not recover after a short retry loop. No customer credits are charged.

Shared daily data-access capacity is exhausted.

details.reason is daily_budget, details.scope is deployment and details.resets_at gives midnight UTC. This shared protection applies to all plans. No customer credits are charged.

What to do · Wait for the reset specified by retry-after; contact support if this persists.

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 request_id without leaking internal details. Inspect credits_used and error.details.billing_status: an unresolved accounting outcome can require reconciliation.

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