> ## Documentation Index
> Fetch the complete documentation index at: https://docs.iotools.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> RFC 9457 problem documents, and the codes to branch on

Every failure is an [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) problem document, served as `application/problem+json`.

```json theme={"system"}
{
  "type": "https://docs.iotools.cloud/errors/insufficient_credits",
  "title": "Insufficient credits",
  "status": 402,
  "code": "insufficient_credits",
  "detail": "This call costs 1 credit and 0 remain in this month's allowance.",
  "request_id": "e4042b29-…"
}
```

## Branch on `code`

<Warning>
  **`code` is the stable field.** `title` and `detail` are human prose and may be reworded at any time without a version bump — never match on them. `type` is a stable documentation URI and is also safe.
</Warning>

## Every code

| Status | `code`                 | What to do                                                               |
| ------ | ---------------------- | ------------------------------------------------------------------------ |
| 400    | `validation_error`     | Fix the inputs. Carries a `fields` map naming each bad one               |
| 401    | `invalid_api_key`      | Missing, malformed or revoked key                                        |
| 402    | `insufficient_credits` | Wait for the monthly reset, or upgrade                                   |
| 403    | `tool_not_allowed`     | This tool exists but has no API endpoint. Use the website — do not retry |
| 404    | `tool_not_found`       | No such slug. Find the right one with `GET /v1/tools/search`             |
| 413    | `payload_too_large`    | Send less. Some tools cap body size                                      |
| 429    | `rate_limited`         | Back off for `retry_after` seconds                                       |
| 500    | `processing_error`     | The tool failed on your input. Retrying identical input won't help       |
| 500    | `internal_error`       | Our fault. Retry, then tell us the `request_id`                          |
| 503    | `tool_disabled`        | Temporarily switched off by us. **Retry shortly**                        |
| 503    | `api_unconfigured`     | Our fault. Retry                                                         |

<Note>
  `tool_not_found` and `tool_disabled` look similar and mean opposite things: one says *delete this from your integration*, the other says *try again in a minute*. That distinction is why they are separate codes.
</Note>

## Validation errors name the field

```json theme={"system"}
{
  "code": "validation_error",
  "status": 400,
  "fields": { "base64String": "Required" },
  "request_id": "e4042b29-…"
}
```

Surface `fields` to whoever supplied the input — it maps one-to-one onto the tool's documented inputs.

## `request_id`

Every response carries one, in three places: the body, the `x-request-id` header, and our server logs. Quoting it turns "it failed once around 14:20" into a query.

You can supply your own by sending an `x-request-id` header, and we will echo it — handy for correlating with your own tracing.

## Nothing costs credits when it fails

Credits are reserved on entry and refunded on **every** 4xx and 5xx. This includes the one-credit floor, so a broken integration in a retry loop cannot drain your allowance.

## MCP

MCP has no HTTP status to carry, so tool failures come back as an MCP error result with the **same code vocabulary** in the text:

```
insufficient_credits: 0 remaining
```

Parse the prefix up to the first colon.

MCP adds two codes of its own, both about the [spending confirmation](/mcp/overview#your-agent-cant-spend-credits-without-asking): `declined_by_user` (you declined the prompt — nothing ran, nothing was charged) and `confirmation_required` (the client can't show a prompt and the call cost more than 50 credits, so it was refused).