Limits and errors

The Queue CallBack MCP server reports a problem in one of two ways: an HTTP error before any tool runs, with a stable code in error.data.code, or a tool result with isError: true and a stable code in structuredContent.error.code. This page lists the limits, every code with its meaning and its fix, and the rules for when an agent may retry.

For AI agents: this page is also available as Markdown at https://queuecallback.com/docs/mcp/errors.md. The whole MCP documentation in one file: https://queuecallback.com/docs/llms-full.txt

Every code on this page has its own anchor, https://queuecallback.com/docs/mcp/errors#<code>, for example #mcp_disabled. Branch on the code, not on the message: messages are written for people and can change.

Limits

These are the limits of the Queue CallBack MCP server and of the Queue CallBack API behind it. The values are the current defaults, and Queue CallBack can change them. A Retry-After header or a retry_after_seconds field in an answer always wins over this table.

HTTP errors

An HTTP error from the Queue CallBack MCP server means the request was refused before any tool ran, so nothing changed. The exceptions are a 500, and a 502 or 504 from the edge, which can come while a tool runs. The server checks a request in this order: the Host name, the browser origin, the credential, the request limits, then the MCP transport rules. A request without a valid credential that passes the first two checks answers 401, even a GET or one with the wrong Content-Type.

Most HTTP errors carry a JSON-RPC error body with "id": null. Its error.code is -32001 for a credential problem (401 and 403) and -32000 for 429 and 5xx. error.data.code is the stable reason. error.data.retry_after_seconds is set, together with a Retry-After header, when waiting and retrying makes sense. Every answer from the server itself carries an X-Request-ID header; quote it when you contact Queue CallBack support. Answers made by the edge (the per-address 429, a 413, a 404 for an unknown path, a 502 or 504) and host_not_allowed have none.

This is the answer to a request without a valid API key or sign-in:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Cache-Control: no-store
WWW-Authenticate: Bearer resource_metadata="https://mcp.queuecallback.com/.well-known/oauth-protected-resource/mcp", error="invalid_token", scope="ivr:read reports:read callbacks:read queues:read org:read"
X-Content-Type-Options: nosniff
X-Request-ID: <request id>

{"error":{"code":-32001,"data":{"code":"invalid_token"},"message":"The credential is missing, malformed or unknown, or the API key has expired, been revoked or been suspended (a key is suspended while the admin who created it is deactivated or no longer in the organization), or the sign-in has ended. Send a valid Queue CallBack API key as Authorization: Bearer \u003ckey\u003e, or sign in again; an organization admin sees each key's status on the portal's API keys page."},"id":null,"jsonrpc":"2.0"}

\u003c and \u003e are JSON escapes for < and >. The message lists every state that gets this answer, because the server cannot tell them apart. The WWW-Authenticate header tells a client where to sign in: resource_metadata points to the discovery document, and scope names the five read scopes a sign-in asks for. Claude and ChatGPT use it to start the sign-in (OAuth sign-in). A client that sends an API key does not need it.

Tool errors

A tool error is a normal JSON-RPC result from the Queue CallBack MCP server, not a protocol error. isError is true, the text content says what happened and how to fix it, and structuredContent.error carries the details. The tool did not do what was asked. Whether anything changed depends on the code: see Retries.

The error object

This is a tool error the Queue CallBack API raised (a rate limit):

{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "isError": true,
    "content": [
      {
        "type": "text",
        "text": "HTTP 429 (rate_limited): Too many requests for this credential or organization; retry after the time in Retry-After. Too many requests; retry after 3 seconds."
      }
    ],
    "structuredContent": {
      "error": {
        "status": 429,
        "code": "rate_limited",
        "message": "Too many requests for this credential or organization; retry after the time in Retry-After",
        "retry_after_seconds": 3,
        "details": {
          "error": "Too many requests",
          "code": "rate_limited",
          "message": "Too many requests for this credential or organization; retry after the time in Retry-After",
          "retry_after_seconds": 3
        }
      }
    }
  }
}

For an API refusal the text reads HTTP <status> (<code>): <message>. <hint>. For a refusal by the MCP server the text is the message. Read structuredContent.error when it is present; otherwise read the code from the text.

Access, scopes and switches

Arguments, confirm tokens and handles

Limits and availability

Callbacks and reporting

add_callback refuses a callback with one of these codes. None of them adds a callback or places a call. For a 4xx answer, details carries the API's answer, whose texts are written for people.

add_callback can also answer idempotency_key_reused, invalid_idempotency_key and the general codes on this page.

IVR flows (Preview)

These codes belong to the IVR flow tools, which are in Preview while the IVR builder is redesigned. Codes may be added or changed; the changelog records changes. edit_flow_draft can refuse an operation with a code that is not listed here; every such refusal names the operation in details.failed_ops, and nothing of the call is applied. The validation issues that validate_flow reports carry codes of their own, which are not listed here: branch on them and show the user the issue's text (Validate, review and publish). The editing loop is on Edit a flow safely.

Answers without a code

Some refusals from the Queue CallBack API carry a status and a message but no code. Branch on status.

Retries

These rules tell an AI agent, or any client of the Queue CallBack MCP server, when to repeat a request, how long to wait, and what to read before repeating a change.

Wait as long as the server says

1. When an answer has a Retry-After header or a retry_after_seconds field (in error.data or structuredContent.error), wait at least that long.
2. When a 429 or 503 comes without a wait time, back off exponentially with jitter: about 1, 2, 4, 8 and 16 seconds, never more than 60 seconds between attempts.
3. Stop after about 5 attempts. Tell the user what failed and give the code (and the X-Request-ID header if the client shows it).
4. After concurrency_limited, run fewer calls at once: at most 4 tool calls in parallel per organization, counting every key.

Repeat reads freely, changes only after reading the state

A read-only tool can be repeated after any error that is about load or availability: rate_limited, concurrency_limited, auth_busy, reporting_busy, interactive_busy, query_timeout (narrow the query first), backend_timeout, backend_unreachable, backend_error, HTTP 5xx.

A tool that changes something is different. After backend_timeout, backend_unreachable, backend_error, result_too_large, no_answer, edit_interrupted, a 5xx status, or a dropped connection, the change may have happened. Never repeat it blindly. Read the state first:

An answer that refused the call before it ran (rate_limited, concurrency_limited, auth_busy, queue_write_limited, requeue_busy, any HTTP error other than a 500 or a 502 or 504 without a JSON-RPC body) changed nothing, and the change can be repeated after the wait.

Confirm tokens are spent on use

A confirm token is spent the moment the server accepts it, before the Queue CallBack API answers, even if the change then fails or is refused by a limit. Every repeat of a confirmed change therefore needs a new token: from validate_flow for publish_flow, and from a first call without confirm_token for requeue_callback, restore_flow_version, update_queue_settings, set_queue_voice and set_queue_language. Show the user what will change and get their agreement again.

A call that fails after its token was accepted says so. Its structuredContent.error carries confirm_token_spent: true and a next_step with the retry steps, and its text ends with the same steps:

A confirm_refused answer changed nothing. With confirm_token_spent: true, the token was used by an earlier call, which may have made the change: read the current state before you get a new token. See confirm tokens.

Requeues place real calls

Every requeue_callback makes the system ring an agent and then call the customer. Never repeat a requeue without checking get_requeue_status first.

If get_requeue_status answers invalid_handle, check the callback with list_callback_queue instead of starting the requeue again. To learn what happened to the first attempt, call requeue_callback again with the same idempotency_key and a new confirm token: when the API recorded the first attempt, it replays the recorded request instead of dialing again. A first attempt that never reached the API runs now, so get the user's agreement for this call too. If the replayed status is failed or conflict and the user agrees to try again, use a new confirm token and a new idempotency_key: the old key only replays the failed attempt.

Idempotency keys

add_callback and requeue_callback take an idempotency_key argument: letters, digits, ., _, : and -, at most 255 characters. A client can send _meta.idempotencyKey on the request instead; the argument wins.

1. Make one new random key, such as a UUID, for each action you intend.
2. Send the same key with every repeat of that action. A repeat returns the recorded answer instead of acting twice, even when that answer was a failure: a requeue recorded as failed or conflict needs a new key to be tried again.
3. Never use the key for a different action. Keys are unique per organization, across all of its keys, and a reused key gets idempotency_key_reused.
4. Send your own key with add_callback. Without one, the server makes a key for that single call only, so a repeat call gets a different key.

For symptoms rather than codes (cannot connect, a tool is missing, numbers are masked), see troubleshooting.