Errors and what you pay

Every error code the API and the MCP endpoint can return, with the HTTP status, the call class, what you pay (₹0 in every row but one) and whether to retry.

Every error response is JSON with ok: false, an error code from the tables below, a message in plain English, charged_paise: 0 where money was at stake, retryable, and request_id (also the X-Request-Id header on every response). Calls that reached the source also carry call_id, class and, on failure, upstream_status and a short upstream_message.

When the source did not answer, or found nothing, and another tool is a second source for the same job, the answer also carries also_try: the tool to try, why, its estimate (estimate_paise, estimate), free_when_no_result and how. Nothing more runs and nothing is charged until you call that tool; it is an ordinary call at its own price, and its input fields can differ from the first tool's.

The rule behind every row: no useful result, no charge. Failed calls, refused calls, empty results and anything rejected before the source was called cost ₹0, and the hold placed on the balance is released in the same transaction that records the outcome.

Over MCP (run_tool and the headline tools) the same body is the tool result's text, with isError set for every row except confirmation_required, which is a quote the agent should show the user. Link to any row by its code: /docs/errors#insufficient_balance.

This table is generated from the one constant in the API's code that every error passes through; a test fails when the two drift.

Rejected before any provider call

The provider was never called. No hold was placed, or it was released in the same transaction. Every row is ₹0.

errorHTTPclassYou payRetryableWhat happenedWhat to do
invalid_request400-₹0noThe request body is not the shape the route expects (issues[] names the fields).Fix the request. tool is a string, input an object.
invalid_input400rejected₹0noThe input does not match the tool's schema; errors[] lists each path and what is wrong, including missing one-of sets. An input nested more than 64 levels deep is refused the same way, before anything reads it.Fix the named fields. inspect_tool / GET /v1/tools/:id shows the schema and an example.
unauthenticated401-₹0noNo API key was sent.Send Authorization: Bearer sk_....
invalid_key401-₹0noThe key is not valid or has been revoked. Repeated failures are rate-limited per IP.Ask the user for a current key from the dashboard. Do not retry with the same key.
insufficient_scope403-₹0noThe key lacks the scope this route needs (run for paid calls, read for status and balance).Use a key with the right scope; the dashboard sets scopes per key.
no_team403-₹0noThe person who signed in through Claude has no team yet (or is only a viewer on every team), so there is no wallet to charge.Ask the user to open the dashboard and create a team (the welcome credit is added then); then reconnect.
connector_revoked401-₹0noThe hidden "Claude connector" key behind this sign-in was revoked in the dashboard, so the connection no longer works.Ask the user to disconnect and reconnect Parel in Claude; a fresh connector key is created on sign-in.
insufficient_balance402rejected₹0noThe balance cannot cover the hold for this call. estimate_paise, balance_paise and topup_url are in the body.Tell the user how to get credit: how_to_get_credit says whether to top up at topup_url or, during the beta, to email Parel. Then stop; do not retry until the balance changes.
unknown_tool404rejected₹0noNo enabled tool has that name (disabled tools answer the same way).Call discover_tools / POST /v1/discover and use a listed name.
unknown_job400-₹0nodiscover_tools / POST /v1/discover / GET /v1/tools was given a job that does not exist; jobs[] lists the valid ones. Over MCP the answer also carries the job index.Use one of jobs[].job, or leave job out and describe the task as query.
not_found404-₹0noNo call with that call_id belongs to this team.Check the id; it is the call_id from the run response.
in_progress409-₹0yesA call with this idempotency key is still running.Poll get_run / GET /v1/runs/:id with its call_id, or retry shortly with the same key.
replay_expired410rejected₹0noThe stored answer for this idempotency key was purged (24 h); original_call_id names the earlier call.Use a new idempotency key to run the call again. It will be charged as a new call.
body_too_large413-₹0noThe request body is over 1 MB.Send a smaller input. Tool inputs are small by design.
idempotency_key_mismatch422rejected₹0noThis idempotency key was already used with a different tool or input.Use a new key. Keys are per exact input.
confirmation_required428-₹0noThe call needs the user's explicit go-ahead: the tool is marked as always needing it (confirm_required: true in inspect_tool / GET /v1/tools/:id) or the estimate is above the confirm threshold (₹200 by default). The body is the full quote: estimate_paise, hold_paise, balance_paise, enough_balance.Tell the user the estimate. If they agree, resend the same input with confirm: true. No call row was made and nothing was held.
budget_exceeded429rejected₹0noA spend cap would be exceeded; cap names it (key_daily, key_monthly, team_daily, team_monthly).Say which cap was hit. The user can raise it in the dashboard; do not retry until then.
daily_free_limit429rejected₹0noToo many of this account's calls today failed or found nothing. Those calls are free, so there is a daily limit on them. resets_at says when it lifts: midnight India time.Tell the user paid tools are paused for this account until resets_at, and that support can lift the limit sooner. Do not retry before then. Quotes, the tool list and free tools still work.
free_accounts_paused429rejected₹0noAccounts that have not yet paid have, together, used up today's allowance for calls that failed or found nothing. Their paid tools are paused; resets_at says when it lifts: midnight India time. Accounts that have paid are not affected.Tell the user paid tools are paused for this account until resets_at, and how to get them back sooner (the message says). Do not retry before then. Quotes, the tool list and free tools still work.
daily_picture_limit429rejected₹0noThis account has stored today's share of screenshots (50 MB a day by default), so screenshot_page was refused before anything was captured. Nothing was charged. resets_at says when it lifts: midnight India time.Tell the user screenshots are paused for this account until resets_at; every other tool still works. Support can raise the allowance (the message gives the address).
rate_limited429-₹0yesToo many paid calls on this key in a minute (300 by default), too many failed sign-ins from one IP, or too many requests from one address to a page that needs no key (/health, /i/, /.well-known/, unknown /go/ links). Retry-After is set.Wait Retry-After seconds, then retry with the same idempotency key.
too_many_in_flight429-₹0yesThis account already has the most paid calls running at once that it may (10 by default). Refused before anything was held or charged; no call was recorded. Retry-After is set.Wait for one of the running calls to finish, then retry with the same idempotency key. Send calls one after another, or a few at a time, rather than all at once.
key_limit_reached409-₹0noThe account already has the most live API keys it may (20 by default); limit says how many. Nothing was created.Revoke a key that is no longer used (dashboard, API keys), then create the new one.
paused503rejected₹0noAll calls are paused by the operator (incident or maintenance).Tell the user and try again later. Nothing is charged while paused.
tool_unavailable503rejected₹0noThe tool exists but has no live provider right now.Use a sibling tool from discover_tools or try later.
team_paused403rejected₹0noThis team's account is paused.The user should contact support from the dashboard.
team_not_found403rejected₹0noThe key's team no longer exists.Ask the user for a key from a current team.
key_revoked401rejected₹0noThe key was revoked moments ago: the paid call was refused when the hold was taken, even though the key was still accepted at the door for up to ten seconds.Ask the user for a current key from the dashboard. Do not retry with this key.
unknown_pack400-₹0noPOST /v1/topup was given a pack id that does not exist; packs[] lists the valid ones.Use one of packs[] (GET /v1/packs shows prices).
payments_not_configured503-₹0noTop-ups are not enabled on this deployment yet.Tell the user; credit is granted by hand during the closed beta.
checkout_failed502-₹0yesThe payment provider refused to open a checkout.Try again in a minute; if it repeats, the user should write to support.

The provider or the route failed

The call reached the provider and did not produce a usable answer. The hold is released; the customer pays ₹0. upstream_status and a short upstream_message are in the body.

errorHTTPclassYou payRetryableWhat happenedWhat to do
image_daily_limit502upstream_error₹0noA screenshot was captured at the moment this account used up today's share of stored screenshots (several calls at once), so the picture was not kept. Nothing was charged.Same as daily_picture_limit: try again after midnight India time, or ask support to raise the allowance.
upstream_timeout502upstream_error₹0yesThe provider did not answer within the tool's timeout.Retry once with the same idempotency key. If the answer may have arrived meanwhile, get_run first.
upstream_unreachable502upstream_error₹0yesA network failure between us and the provider.Retry once with the same idempotency key.
upstream_busy502upstream_error₹0yesThe route is saturated or the provider's shared capacity is busy.Wait retry_after_seconds if present, then retry with the same idempotency key.
upstream_unavailable502upstream_error₹0yesThe provider is out of capacity or paused upstream; retry_after_seconds may say when it resets.Wait, then retry with the same idempotency key, or use a sibling tool.
upstream_error502upstream_error₹0yesThe provider answered 5xx or with a body we could not read.Retry once with the same idempotency key; if it repeats, change the tool.
upstream_balance_empty502upstream_error₹0noOur own prepaid balance upstream is empty. The operator is paged automatically.Tell the user the service is temporarily unavailable; try again in an hour. Do not loop.
estimate_too_low502upstream_error₹0noThe real price of this input would exceed the per-call cost cap derived from the hold (for example far more results than estimated).Ask for fewer results (a smaller count) or a narrower input, then run again.
upstream_<status>502upstream_error₹0noThe route itself refused our request with that 4xx (a configuration problem on our side, not the provider).Do not retry the same call. Try a sibling tool; the operator sees these in the logs.
vendor_error_body422vendor_error₹0noThe provider answered 2xx but the body is an error envelope.Treat it as a refusal: change the input or the tool. Never loop.
vendor_<status>422vendor_error₹0noThe provider refused the call with that 4xx (bad parameters for that provider, not found, blocked target). upstream_message carries a short reason.Fix the input (upstream_message), or use a sibling tool. Never loop.
internal_error500upstream_error₹0yesSomething failed on our side after the hold was placed. The hold is released and the call is finished as free.Retry with the same idempotency key. If you have a call_id, get_run shows its final state.

Not errors: codes you may see on a finished call

Returned as error by get_run / GET /v1/runs/:id on calls that completed.

errorHTTPclassYou payRetryableWhat happenedWhat to do
no_result200ok_free₹0noThe provider answered but by the tool's rule there was nothing useful in it (no email, empty list, empty page).Say so. Nothing was charged. A different input may find something; the same input will not.
cost_header_missing200okthe shown pricenoA successful answer arrived without the upstream cost; the price quoted for this input was charged (never more than the hold) and the call is flagged for reconciliation.Nothing. If the charge looks wrong, use Report bad result on the call.

Classes

classMeaningYou pay
okA result came backthe real price of the call, normally the shown price; if the provider bills more than the hold, the extra is taken only when the balance covers it
ok_freeNothing found (error: no_result), or a free tool₹0
replaySame idempotency key within 24 h: the stored answer₹0
runningA slow job is still running; poll get_runnothing yet; the hold stays until it finishes
vendor_errorThe provider refused the call₹0
upstream_errorTimeout, provider down, route or our fault₹0
rejectedRefused before the provider was called₹0

What an ok call is charged when a source bills more than expected: How it works.

Retrying safely

  • retryable: true: retry once with the same idempotency_key, after retry_after_seconds or Retry-After when present. A finished call replays for ₹0; a failed one runs again.
  • Lost the answer (your side timed out)? Read GET /v1/runs/:id with the call_id before running again. No call_id? Rerun with the same idempotency_key.
  • retryable: false: the same call will fail the same way. Change the input, the tool, or wait for the user (balance, budget, confirmation).

Two codes outside the table

The sign-in path of the MCP endpoint can also answer invalid_token (401: the token is invalid, expired or was not minted for the Parel connector) and forbidden (403: the signed-in person is only a viewer on their teams). Both are ₹0. Authentication.

This page as Markdown: /docs/errors.md. Something wrong or missing: hello@parel.si.