1. Winvariant
  2. Docs
  3. Errors
Docs

Errors

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

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.

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

The codes

CodeHTTPWhenWhat to do
unauthorized401No 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_scope403The 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_found404The 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.
invalid400The 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_credits402The 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_human409The 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.
refused422The 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_conflict409The 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_limited429Too many calls: per key a minute, per owner a minute or a day.Wait for Retry-After seconds. Nothing was run.
too_large413A result would be larger than 60 KB.Ask for less: a filter, a shorter period, a smaller limit.
internal500The 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.

Last updated 16 November 2026.