# Whizbrew errors: what each one means and what to do

No failed or refused call is charged. Every error of `https://whizbrew.com/v1/call/<tool>` and of `call_tool` over MCP has the same shape:

```
{"error": {"kind": "rate_limited", "message": "…", "blame": "source", "hint": "…", "retry_after_s": 30}, "meta": {"outcome": "error", "price_micros": 0}}
```

- `kind`: which error (the table below). `message`: one sentence for a person.
- `blame`: who has to change something. `caller`: change the request. `us` or `source`: not your fault.
- `hint`: what to do next. `retry_after_s`: when waiting helps, how long (the same number is in the `Retry-After` header).
- `did_you_mean`, `accepted`: the nearest tool or argument names, on an unknown tool or argument.

| kind | HTTP | do |
|---|---|---|
| bad_input | 400 | Fix the arguments (`accepted` and `did_you_mean` name them). The same call fails again. |
| unknown_tool | 404 | Use a name from `did_you_mean`, or search_tools. |
| not_found | 404 | Nothing exists for these arguments. Check the spelling once, then tell the user. |
| unauthorized | 401 | The key is missing or wrong. Get a key: https://whizbrew.com/llms.txt?a=79eecbf50529, section B. |
| insufficient_balance | 402 | Stop and tell the user: the credit is used up. They add credit in the dashboard, https://whizbrew.com/app#credit. |
| max_cost_exceeded | 402 | The price (`price_micros`) is above the maximum you set. Raise it or pick a cheaper tool. |
| spend_cap_reached | 402 | A spending cap the user set is reached. Stop and tell the user; `limit.resets_at` says when it resets. |
| rate_limited | 429 | Wait `retry_after_s` seconds, then send the same call. With `blame: caller` you sent too much at once: send fewer calls at the same time. |
| repeated_call | 429 | The same tool with the same arguments came 5 times in a minute. Use the answer you have, or change the arguments. |
| in_progress | 409 | A call with this `Idempotency-Key` still runs. Wait `retry_after_s`, send it again. |
| idempotency_conflict | 409 | The `Idempotency-Key` belongs to another call. Use a new key for a new call. |
| not_configured | 503 | The tool cannot answer now. Pick another with search_tools. |
| upstream | 502 | The source did not answer. Send it once more later; fails again: tell the user, or pick another tool. |
| internal | 500 | Our fault. Send it once more later; fails again: tell the user. |

A call that answers with nothing found is not an error: it is `meta.outcome: "miss"`, HTTP 200, price 0.

More: [llms.txt](https://whizbrew.com/llms.txt?a=79eecbf50529) · [docs](https://whizbrew.com/docs?a=79eecbf50529) · [pricing](https://whizbrew.com/pricing?a=79eecbf50529)
