# Errors

A refusal has a stable code and a message that says what to do next.

**Docs:** [Quickstart](/docs) · [Authentication](/docs/authentication) · [Tool reference](/docs/tools) · **Errors** · [Limits](/docs/limits) · [What stays human](/docs/human-steps) · [The skill](/docs/skill)

## The shape

Over HTTP a refusal is JSON with a stable `code` and a `message` written for you to act on. Branch on the code, show the message.

```json
{
  "code": "forbidden_scope",
  "message": "Make new ads needs the create permission, which the owner did not give this API key. …",
  "scope": "create"
}
```

## The codes

| Code | HTTP | When | What to do |
| --- | --- | --- | --- |
| `unauthorized` | 401 | No API key was sent, or it is unknown, revoked or past its end date. | Send `Authorization: Bearer <key>`. The owner makes a key on their account page. |
| `forbidden_scope` | 403 | The key doesn't carry the permission this tool needs. | Ask the owner for a key with that permission. A key's permissions can't be widened afterwards. |
| `not_found` | 404 | The tool, the business or the ad doesn't exist, or isn't one this key may use. | List what exists: `GET /api/v1/tools`, `list_businesses`, `list_ads`. |
| `invalid` | 400 | The body isn't a JSON object, or an argument is missing or of the wrong kind. | The message names the argument. The tool's schema is in `GET /api/v1/tools`. |
| `insufficient_credits` | 402 | The plan (or the free preview) has too little left for what was asked. | Tell the owner. Buying a plan or credits is done by the owner, never by an agent. |
| `needs_human` | 409 | The next step is a person's: a consent screen, a check that a person is there, a payment, the rights tick or a spend cap. | Hand the owner the link or the sentence in the message, and wait. |
| `refused` | 422 | The app's own rules said no: nothing to undo, an ad that isn't running, a quote that ran out, was used or doesn't match. | The message says why. For a quote: call the tool again without `confirm`. |
| `idempotency_conflict` | 409 | The `Idempotency-Key` was used before with another tool or other arguments, or the first request with it is still running. | Use a new key for a new request; repeat the same request with the same key. |
| `rate_limited` | 429 | Too many calls: per key a minute, per owner a minute or a day. | Wait for `Retry-After` seconds. Nothing was run. |
| `too_large` | 413 | A result would be larger than 60 KB. | Ask for less: a filter, a shorter period, a smaller `limit`. |
| `internal` | 500 | The server failed. It was logged. | Try again later. A request sent with an `Idempotency-Key` is safe to repeat. |

## On the connector

The connector answers in its protocol's own way: a refused tool call is a tool result marked as an error, with the same message; a missing permission on a signed-in connection is a step-up challenge (HTTP 403, `insufficient_scope`) that lets the assistant ask its person for more. A key can't step up: it gets the message.

## A dry run that says no is not an error

A tool that is asked twice answers its dry run with HTTP 200 even when it can't go on: the answer has `blocked` with the reason and no `quoteId`. Tell your person what it says.

---

HTML version: https://winvariant.com/docs/errors · Last updated: 2026-11-16 · All pages: https://winvariant.com/llms.txt
