Documentation
Errors
JSON-RPC (MCP)
| Code | Meaning |
|---|---|
-32700 | Parse error (malformed JSON) |
-32600 | Invalid request (wrong envelope shape, or a JSON array body — batching is not supported) |
-32601 | Method not found |
-32602 | Invalid params (including a tool's own argument validation failing) |
-32603 | Internal error |
-32001 | Missing, malformed, unknown or revoked token |
-32002 | Per-minute or per-day limit consumed |
-32003 | The organization does not hold the Bellaso agent entitlement |
Transport errors vs. tool errors
A transport error and a tool error are different things. A failed tool call — including a
guardrail refusal — comes back as a normal tools/call result with "isError": true at HTTP
200. Only protocol-level problems (bad JSON, unknown method, auth, rate limit, entitlement) use
the error envelope.
HTTP (REST)
| Status | error | Meaning |
|---|---|---|
400 | validation_error / invalid_json | Body was not a JSON object, or arguments failed the tool's schema. path names the failing argument. |
401 | unauthorized | Missing, malformed, unknown or revoked token — all four are reported identically. |
402 | subscription_required | The organization's agent entitlement is not active. Opaque by design: no tier or lapse detail. |
403 | tool_denied | The tool refused the call — an unentitled module, or an out-of-policy argument. Not a failure; a guardrail. |
404 | not_found | No such tool, or this token may not call it. Deliberately indistinguishable. |
405 | method_not_allowed | Wrong HTTP method for the path; the Allow header names the right one. |
413 | payload_too_large | Body exceeds 64 KiB. |
429 | rate_limited | Limit consumed. Retry-After carries the seconds to wait. |
500 | tool_error / internal_error | The tool failed. tool_error carries the tool's own message; internal_error means the detail is in the audit log, not the response. |
503 | service_unavailable | Token lookup itself failed. A transient infrastructure fault is never reported as a bad token. |
Every REST error body is the same flat shape: { error, message, path?, request_id }.
Last modified on