Error and reason codes

The JSON-RPC codes, the error envelope, every reason the MAQPNA gateway returns, the SDK error for each, and the CLI exit codes.

When the MAQPNA gateway refuses or holds a call, it says why in one envelope with a stable reason. Match on the reason, not on the message text. This page lists the JSON-RPC codes, the envelope, every published reason with the SDK error it becomes and what to do, and the exit codes of the maqpna CLI.

flowchart LR
    G[Gateway decision] --> C{JSON-RPC code}
    C -->|-32001| PD["PolicyDenied (reason: policy_denied, dlp:…, revoked, budget_exceeded:…)"]
    C -->|-32002| AP["ApprovalPending (reason: approval_required)"]
    C -->|-32003| UA["Unauthorized (reason: unauthorized, missing_scope:…)"]
    C -->|-32603| RE["RPCError (reason: audit_unavailable, internal_error)"]
    C -->|-32020 / -32022| PR["HeaderMismatch / UnsupportedProtocolVersion"]

JSON-RPC codes#

In sync mode (the default) a call that needs approval does not return -32002: the gateway holds it until a person decides, then returns the result or -32001 with approval_denied or approval_expired. See Human approvals.

The error envelope#

Every error the gateway generates carries the same fields in error.data:

Real envelopes from a local MAQPNA (maqpna dev up), as maqpna call prints them:

# a rule denied the call
error -32001: denied by policy baseline-guardrails rule never-touch-system-namespaces: system namespaces are off-limits to agents
data: {"detail":"system namespaces are off-limits to agents","domain":"maqpna.com","policy":"baseline-guardrails","reason":"policy_denied","rule":"never-touch-system-namespaces"}

# an approver denied the held call
error -32001: denied by policy default-agent-policy rule destructive-needs-human: approval_denied by reviewer@localhost (apr_902e3a670541349ffc7844a3)
data: {"detail":"approval_denied by reviewer@localhost (apr_902e3a670541349ffc7844a3)","domain":"maqpna.com","policy":"default-agent-policy","reason":"approval_denied","rule":"destructive-needs-human"}

# the session was revoked with maqpna kill
error -32001: revoked: calls of this token are blocked by revocation/breakglass/51c5fe6e6ada148d (INC-1: test)
data: {"domain":"maqpna.com","policy":"revocation/breakglass/51c5fe6e6ada148d","reason":"revoked","rule":""}

A bad token, as raw JSON-RPC:

{"jsonrpc":"2.0","id":null,"error":{"code":-32003,"message":"unauthorized: identity: malformed token: expected 3 segments","data":{"domain":"maqpna.com","reason":"unauthorized"}}}

A DLP block (the profile is the rule):

data: {"domain":"maqpna.com","policy":"dlp","reason":"dlp:pan","rule":"payments"}

Model route errors#

The model route (/llm/<route>/v1/*) answers OpenAI-style, so OpenAI SDKs raise their normal API errors. type is the error class, code keeps its earlier value for compatibility, and reason is the published token:

{"error":{"code":"route_not_found","domain":"maqpna.com","message":"unknown model route \"nope\"","reason":"route_not_found","type":"maqpna_not_found"}}

The types are maqpna_unauthorized, maqpna_policy_denied, maqpna_approval_required, maqpna_budget_exceeded (HTTP 402), maqpna_rate_limited, maqpna_egress_denied, maqpna_dlp_blocked, maqpna_revoked, maqpna_audit_unavailable, maqpna_upstream_error, maqpna_not_found and invalid_request_error.

Admin API errors#

The admin API (/v1/*, used by the CLI, the console and MAQPNA Desk) answers {"error": "<message>"} for now. Moving it to the same envelope is Planned.

Reasons#

The list is append-only: a reason is never renamed or removed in v1alpha1. The audit ledger uses the same words, so a reason in an error matches the reason in the audit record.

Authentication and authorisation#

These come with -32003 (Unauthorized) on tool calls, or HTTP 401/403 on the model route.

Policy#

These come with -32001 (PolicyDenied).

Approvals#

Routing and resources#

Agent-to-agent (A2A)#

Availability#

These usually come with -32603 (RPCError), or TransportError when the gateway's answer is not JSON-RPC.

Protocol#

CLI exit codes#

Every maqpna command (and the maqpna-install plugin) uses the same exit codes, so scripts and CI can branch on them:

maqpna dev run exits with your command's exit code. For example, a denied maqpna call under it:

maqpna dev: session dev-0cf86530 (agent coder, namespace dev, on behalf of you@localhost)
error -32001: denied by policy baseline-guardrails rule never-touch-system-namespaces: system namespaces are off-limits to agents
data: {"detail":"system namespaces are off-limits to agents","domain":"maqpna.com","policy":"baseline-guardrails","reason":"policy_denied","rule":"never-touch-system-namespaces"}
maqpna dev: dev-0cf86530: 1 deny, cost $0.0000 (maqpna dev timeline --last)
$ echo $?
3

Next: Python SDK, Troubleshooting.