Error envelope and reason codes#

When the gateway refuses or cannot complete a call, it says why in a machine-readable way. Every error it generates carries the same envelope fields, wherever the protocol puts them (cmd/maqpna-gateway/envelope.go):

The reason list is append-only: no token is removed or renamed within v1alpha1. A test (TestReasonEnumLiterals) fails the build when a reason literal in the gateway is not in the list.

Where the envelope lives#

How a client should read an error#

flowchart TD
    E[Error from the gateway] --> D{"domain == maqpna.com?"}
    D -- no --> P["Protocol or upstream error:<br/>handle per MCP or A2A spec"]
    D -- yes --> T["token = reason up to the first colon"]
    T --> G{token group}
    G -- "approval_required" --> W["Wait or retry with<br/>X-Maqpna-Approval-Id"]
    G -- "auth: unauthorized, missing_token,<br/>token_expired, ..." --> R["Refresh the session token<br/>(re-read MAQPNA_TOKEN_FILE)"]
    G -- "rate_limited" --> B["Back off: Retry-After"]
    G -- "policy, approvals, routing" --> S["Stop and report:<br/>a retry will get the same answer"]
    G -- "availability:<br/>upstream_unavailable, audit_unavailable" --> X["Retry with backoff"]

1. Check domain. Only maqpna.com errors use this list; A2A reuses JSON-RPC codes such as -32001 (TaskNotFound) with its own meaning.
2. Take the token: the text before the first :. Never match on message or detail.
3. Decide by group: refresh credentials for authentication errors, back off for rate_limited (honour Retry-After), retry later for availability errors, and stop for policy decisions.

JSON-RPC codes and HTTP status#

Model-route error types: maqpna_unauthorized (401/403), maqpna_policy_denied (403), maqpna_approval_required (403), maqpna_revoked (403), maqpna_dlp_blocked (403), maqpna_egress_denied (403), maqpna_budget_exceeded (402), maqpna_rate_limited (429), maqpna_not_found (404), maqpna_upstream_error (502), maqpna_audit_unavailable (503) and invalid_request_error (400).

The reason list#

Aliases accepted on input and mapped to the published token: expired → token_expired, bad_signature → token_signature_invalid, audience → token_audience_mismatch, guard_blocked → guard, tokens_per_minute → rate_limited. Audit records use the same vocabulary, plus annotations of allowed calls such as intent, model_override and upstream_status.

What you see#

A budget denial on an MCP call:

{"jsonrpc":"2.0","id":12,"error":{"code":-32001,"message":"denied by policy budget rule agent-day: budget_exceeded:agent/day","data":{"domain":"maqpna.com","reason":"budget_exceeded:agent/day","policy":"budget","rule":"agent-day"}}}

The same class of error on a model call (HTTP 402):

{"error":{"message":"agent budget (day) exhausted for team-a/coder: spent 10.000412 of 10.000000 USD","type":"maqpna_budget_exceeded","code":"budget_exceeded","reason":"budget_exceeded","domain":"maqpna.com"}}

The same on the A2A HTTP+JSON binding (HTTP 403):

{"error":{"code":403,"status":"PERMISSION_DENIED","message":"denied by policy budget rule agent-day: budget_exceeded:agent/day","details":[{"@type":"type.googleapis.com/google.rpc.ErrorInfo","reason":"BUDGET_EXCEEDED","domain":"maqpna.com","metadata":{"jsonrpcCode":"-32001","policy":"budget","reason":"budget_exceeded:agent/day","rule":"agent-day"}}]}}

The amounts are illustrative; the field names, codes, tokens and message patterns come from deniedError, budgets.go and a2a_rest.go. In the ledger the rule of this denial is written budget/agent-day. The CLI follows the same pattern for its own errors (errors.golden):

$ maqpna approvals list
✗ --gateway is required
  Pass --gateway URL, set MAQPNA_GATEWAY_URL, or save it in a context once:
  → maqpna context set NAME --gateway URL --use

Related#

• Gateway request pipeline
• Policies, rules and decisions
• LLM call governance
• A2A call with delegation