MCP error reference

When a tool call fails, the Aeris MCP server returns a stable, structured envelope so your client can branch on the error rather than parse free text. Every code below has its own page with the exact response shape, retry rules, and the fields you can rely on in details.

Response envelope

Every failure — 4xx or 5xx — carries this shape on the response body:

{
  "ok": false,
  "request_id": "uuid-v4",
  "tool": "read_overview",
  "error": "Human-friendly message.",
  "error_envelope": {
    "code": "ENTITLEMENT_LOCKED",
    "message": "Human-friendly, one sentence.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/entitlement-locked",
    "retryable": false,
    "retry_after_ms": null,
    "details": { }
  }
}

The top-level error string is kept for backwards compatibility. New clients should read error_envelope.

Codes

Code	HTTP	Retryable	Meaning
`AUTH_REQUIRED`	401	no	Missing or invalid bearer.
`AUTH_EXPIRED`	401	no	Bearer expired mid-session.
`ENTITLEMENT_LOCKED`	403	no	Plan does not include this tool.
`SCOPE_INSUFFICIENT`	403	no	OAuth grant is missing a required scope.
`VIEWER_READ_ONLY`	403	no	Admin view-as session — writes disabled.
`INVALID_INPUT`	422	no	Input failed schema or business validation.
`IDEMPOTENCY_REQUIRED`	422	no	Mutating tool called without `idempotency_key`.
`IDEMPOTENCY_CONFLICT`	409	no	Same key, different payload.
`NOT_FOUND`	404	no	Unknown resource, tool, or empty range.
`CONFLICT`	409	no	Target already in the requested state.
`RATE_LIMITED`	429	yes	Per-user or per-org QPS hit.
`CONNECTION_EXPIRED`	424	no	Partner OAuth needs reconnect.
`INSUFFICIENT_CREDIT`	402	no	Wallet empty for a paid action.
`UPSTREAM_UNAVAILABLE`	502	yes	Partner API 5xx / DNS / TLS fault.
`TIMEOUT`	504	yes	Tool exceeded its `timeoutMs`.
`INTERNAL`	500	yes	Unclassified server error.

Codes are stable UPPER_SNAKE strings. New codes may be added; existing codes will not be renamed inside a major MCP protocol version.

​Response envelope

​Codes

Response envelope

Codes