# Tool errors

> Error codes specific to the tool endpoints and what to do about each.

Tool errors use the [usual error shape](https://clonvo.com/docs/errors.md), and carry the call’s generation id in the `x-clonvo-generation-id` header. These codes are specific to tools:

| Status | Code | When, and what to do |
| --- | --- | --- |
| `404` | `tool_not_found` | The tool id in the URL doesn’t exist. Use an id from `GET /v1/tools`. |
| `400` | `invalid_tool_arguments` | `arguments` doesn’t match the tool’s schema: a missing or unknown argument, or a value out of range. `param` names the argument, for example `arguments.max_results`. |
| `400` | `tool_requires_own_key` | No enabled key for any provider that can serve the tool, after your `provider` settings, and the call can’t run on Clonvo credits because your settings exclude `clonvo` or credits aren’t offered for it. Add a key under **Provider keys** ([Bring your own tool keys](https://clonvo.com/docs/tool-keys.md)), or loosen `only` and `ignore`. |
| `400` | `no_allowed_providers` | Your `provider` settings exclude every provider that serves the tool. |
| `402` | `byok_requires_paid_plan`, `insufficient_credits` | Your organization is on Free. Buy credits to move to Pay as you go. |
| `402` | `byok_fee_requires_credits`, `insufficient_credits`, `key_limit_exceeded` | There aren’t enough credits for the call on Clonvo credits even at its lowest cap, or the call couldn’t be served within the lower cap your credits allow, or there aren’t enough for the BYOK fee past the monthly allowance, or the API key’s spending limit can’t cover it. The message says which. See [Tool billing](https://clonvo.com/docs/tool-billing.md). |
| `503` | `tools_unavailable` | Web tools on Clonvo credits are temporarily unavailable. Try again in a few minutes, or add your own key. A tool that runs only on Clonvo credits (`company_enrich`, `company_news`, `company_jobs`, `people_enrich`) has no key to fall back to. |
| `429` | `tool_spend_limit_reached` | Your organization reached the spending limit Clonvo set for web tools on credits. Try again later, or add your own key. |
| `403` | `tools_blocked` | Web tools on Clonvo credits are turned off for your organization. Contact support, or add your own key. |
| `404` | `tool_job_not_found` | No job with that id for your organization, or it finished more than 24 hours ago. |
| `502` | `route_failed`, `tool_price_limit` | The call couldn’t be served on Clonvo credits, or not within Clonvo’s price cap for the call. Try again shortly. |

A [job](https://clonvo.com/docs/jobs.md) that fails carries the error in its `error` field. Two codes are specific to jobs: `job_timeout`, when a job runs longer than 30 minutes (45 for `web_research`), and `step_limit_reached`, when a [`browser_task`](https://clonvo.com/docs/browser-task.md) reaches `max_steps` without finishing.

## Provider errors

An error from one of your own-key providers starts with the provider’s name, for example `Tavily is rate-limiting this key (429).`, and keeps the provider’s status where it’s meaningful. Errors on Clonvo credits don’t name a provider.

Over MCP, a problem with the call comes back as a tool result with `isError: true` and the same message; see [MCP](https://clonvo.com/docs/mcp.md#errors).