Errors and limits

When a tool call fails, Cademí MCP returns an error with a stable code, a message, and the API request_id when there is one. This page lists the codes, what to do for each, and the limits on response size, time, and load.

Error format

A failed call is a tool result with isError: true. Its text starts with the code and the message. When the items of the API error carry a reason, the text adds the api_code and those reasons in parentheses, at most five, followed by …+N when there are more, for example (feature_disabled, reason: first_import_requires_release). The text ends with the request_id when there is one. structuredContent carries the error as an object:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests.",
    "retryable": true,
    "api_code": "rate_limit_exceeded",
    "request_id": "01J8Z3ZQ4H8K2M0T1S9P7YQF5C",
    "retry_after_seconds": 12,
    "details": { "blocked_by": ["key"] }
  }
}

Codes

The error codes of the API behind api_code are listed in Errors.

Uncertain results

When a call that changes data fails with OPERATION_TIMEOUT, OPERATION_FAILED, or API_UNAVAILABLE, or with api_code set to idempotency_in_progress, the change may or may not have been applied. The error then brings the key the call used in details.idempotency_key, with retryable: true, and its message says to retry with it. Call the tool again with the same arguments and that idempotency_key: if the first attempt was recorded, the API returns its result and applies nothing new. This works whether you set the key yourself or let the server generate it. How idempotency works in the API is described in Errors.

Request IDs

When an error comes from the API, it keeps the API's request_id. It is the same identifier as the X-Request-Id header and the audit entry of the call. Composite tools also include the request_id in each entry of warnings for a part that could not be read.

Include the request_id when you report a problem (Report a problem).

Response size

A tool result has a size limit. When a result goes over it:

1. Very long text values are shortened, and each one ends with a note that says how many characters were omitted.
2. If the result is still too large, items are removed from the end of its largest list until it fits.

A shortened result says so with truncated: true and a truncation object:

{
  "truncated": true,
  "truncation": {
    "hint": "Some items were omitted to fit the response size limit. Call again with a smaller `limit` and follow `page.next_cursor` to see every item.",
    "arrays": [{ "path": "items", "returned": 38, "omitted": 12 }]
  }
}

When the API result is far above the limit, the tool returns OUTPUT_TOO_LARGE instead. In both cases, ask for less: a smaller limit, filters, or the next page.

Composite tools also read a bounded amount of data. A list they could not read in full has complete: false, and a content tree expands a bounded number of modules: a module that was not expanded has children_complete: false.

Time and load

• Time limit. Each API call a tool makes has a time limit. A call that goes over it fails with OPERATION_TIMEOUT. Composite tools make several API calls, some of them in parallel.
• Cancellation. If your client cancels a tool call, the server stops it, with the code OPERATION_FAILED. A change that the call already sent to the API may still be applied.
• Server capacity. When the server is busy, a call waits briefly for a slot. If none frees up, it fails with CAPACITY_EXHAUSTED and retry_after_seconds.
• API limits. Tool calls count toward the API limits of your account, like calls from any other client. See Limits, quotas, and retention.