> Parel documentation. Index of every page: https://parel.si/docs/llms.txt. This page in HTML: https://parel.si/docs/errors

# 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.

| `error` | HTTP | `class` | You pay | Retryable | What happened | What to do |
|---|---|---|---|---|---|---|
| `invalid_request` | 400 | - | ₹0 | no | The request body is not the shape the route expects (`issues[]` names the fields). | Fix the request. `tool` is a string, `input` an object. |
| `invalid_input` | 400 | `rejected` | ₹0 | no | The 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. |
| `unauthenticated` | 401 | - | ₹0 | no | No API key was sent. | Send `Authorization: Bearer sk_...`. |
| `invalid_key` | 401 | - | ₹0 | no | The 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_scope` | 403 | - | ₹0 | no | The 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_team` | 403 | - | ₹0 | no | The 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_revoked` | 401 | - | ₹0 | no | The 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_balance` | 402 | `rejected` | ₹0 | no | The 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_tool` | 404 | `rejected` | ₹0 | no | No enabled tool has that name (disabled tools answer the same way). | Call `discover_tools` / `POST /v1/discover` and use a listed name. |
| `unknown_job` | 400 | - | ₹0 | no | `discover_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_found` | 404 | - | ₹0 | no | No call with that `call_id` belongs to this team. | Check the id; it is the `call_id` from the run response. |
| `in_progress` | 409 | - | ₹0 | yes | A 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_expired` | 410 | `rejected` | ₹0 | no | The 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_large` | 413 | - | ₹0 | no | The request body is over 1 MB. | Send a smaller input. Tool inputs are small by design. |
| `idempotency_key_mismatch` | 422 | `rejected` | ₹0 | no | This idempotency key was already used with a different tool or input. | Use a new key. Keys are per exact input. |
| `confirmation_required` | 428 | - | ₹0 | no | The 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_exceeded` | 429 | `rejected` | ₹0 | no | A 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_limit` | 429 | `rejected` | ₹0 | no | Too 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_paused` | 429 | `rejected` | ₹0 | no | Accounts 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_limit` | 429 | `rejected` | ₹0 | no | This 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_limited` | 429 | - | ₹0 | yes | Too 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_flight` | 429 | - | ₹0 | yes | This 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_reached` | 409 | - | ₹0 | no | The 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. |
| `paused` | 503 | `rejected` | ₹0 | no | All calls are paused by the operator (incident or maintenance). | Tell the user and try again later. Nothing is charged while paused. |
| `tool_unavailable` | 503 | `rejected` | ₹0 | no | The tool exists but has no live provider right now. | Use a sibling tool from `discover_tools` or try later. |
| `team_paused` | 403 | `rejected` | ₹0 | no | This team's account is paused. | The user should contact support from the dashboard. |
| `team_not_found` | 403 | `rejected` | ₹0 | no | The key's team no longer exists. | Ask the user for a key from a current team. |
| `key_revoked` | 401 | `rejected` | ₹0 | no | The 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_pack` | 400 | - | ₹0 | no | `POST /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_configured` | 503 | - | ₹0 | no | Top-ups are not enabled on this deployment yet. | Tell the user; credit is granted by hand during the closed beta. |
| `checkout_failed` | 502 | - | ₹0 | yes | The 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.

| `error` | HTTP | `class` | You pay | Retryable | What happened | What to do |
|---|---|---|---|---|---|---|
| `image_daily_limit` | 502 | `upstream_error` | ₹0 | no | A 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_timeout` | 502 | `upstream_error` | ₹0 | yes | The 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_unreachable` | 502 | `upstream_error` | ₹0 | yes | A network failure between us and the provider. | Retry once with the same idempotency key. |
| `upstream_busy` | 502 | `upstream_error` | ₹0 | yes | The 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_unavailable` | 502 | `upstream_error` | ₹0 | yes | The 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_error` | 502 | `upstream_error` | ₹0 | yes | The 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_empty` | 502 | `upstream_error` | ₹0 | no | Our 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_low` | 502 | `upstream_error` | ₹0 | no | The 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>` | 502 | `upstream_error` | ₹0 | no | The 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_body` | 422 | `vendor_error` | ₹0 | no | The 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>` | 422 | `vendor_error` | ₹0 | no | The 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_error` | 500 | `upstream_error` | ₹0 | yes | Something 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.

| `error` | HTTP | `class` | You pay | Retryable | What happened | What to do |
|---|---|---|---|---|---|---|
| `no_result` | 200 | `ok_free` | ₹0 | no | The 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_missing` | 200 | `ok` | the shown price | no | A 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

| `class` | Meaning | You pay |
|---|---|---|
| `ok` | A result came back | the 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_free` | Nothing found (`error: no_result`), or a free tool | ₹0 |
| `replay` | Same idempotency key within 24 h: the stored answer | ₹0 |
| `running` | A slow job is still running; poll `get_run` | nothing yet; the hold stays until it finishes |
| `vendor_error` | The provider refused the call | ₹0 |
| `upstream_error` | Timeout, provider down, route or our fault | ₹0 |
| `rejected` | Refused before the provider was called | ₹0 |

What an `ok` call is charged when a source bills more than expected: [How it works](https://parel.si/docs/how-it-works.md#if-a-source-bills-more-than-expected).

## 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`](https://parel.si/docs/api/runs.md) 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](https://parel.si/docs/api/authentication.md#oauth).
