Docs: Quickstart · Authentication · Tool reference · Errors · Limits · What stays human · The 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.
{
"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.
Last updated 16 November 2026.