# 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 |

:::info{title="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 }`.