MCP Error Contract

The Closient MCP server exposes the same business operations as the REST API (GTIN validation, resolution, product lookup, QR-URL generation, more to come) but speaks JSON-RPC 2.0 instead of HTTP. This page documents how MCP tools surface failures so agents can react predictably — distinguishing “GTIN not found” from “rate limited” from “internal error” without parsing free-form strings.

Envelope shape

When a tool fails, the result it returns to the client has an error field matching the JSON-RPC 2.0 error-object shape:

{
  "error": {
    "code": -32200,
    "message": "Not Found",
    "data": {
      "type": "https://closient.com/docs/errors/not_found",
      "title": "Not Found",
      "status": 404,
      "detail": "No product found for GTIN 00614141123452",
      "error_code": "not_found",
      "retryable": false,
      "timestamp": "2026-04-26T02:34:56+00:00"
    }
  }
}

The data payload is an RFC 9457 Problem Details document — the same structure the REST API returns under Content-Type: application/problem+json. Agents that already understand Closient’s REST error shape do not need a second mapping. Successful tool calls do not include an error key — the tool’s normal payload is returned directly.

Code table

JSON-RPC error codes are stable and grouped by failure class:

Code	Class	Meaning	Retryable?
`-32001`	Transport / authentication	Missing or invalid token (`unauthorized`).	After auth
`-32002`	Transport / authentication	Token lacks required scope (`forbidden`).	No
`-32003`	Transport / authentication	Rate limit exceeded (`rate_limited`). See `retry_after`.	Yes
`-32100`	Request validation	Malformed request (`bad_request`).	No
`-32101`	Request validation	Field-level validation error (`validation_error`).	No
`-32102`	Request validation	Semantically invalid (`unprocessable_entity`).	No
`-32200`	Business rule	Resource does not exist (`not_found`).	No
`-32201`	Business rule	State conflict, e.g. already claimed (`conflict`).	No
`-32300`	Upstream / internal	Unexpected server error (`internal_error`).	Backoff

Adding new codes within these ranges is non-breaking. Renumbering existing codes is a breaking change.

Common errors per tool

Tool	Likely codes
`ping`	none — health check has no failure modes.
`validate_gtin`	none — invalid GTINs return `valid: false` in payload.
`resolve_gtin`	`-32101` (invalid GTIN), `-32200` (no rule).
`lookup_product`	`-32101` (invalid GTIN). Missing GTINs return `found: false` rather than an error.
`generate_qr_url`	`-32101` (invalid GTIN), `-32002` (missing `qr:generate` scope, when auth wires up).

Handling errors in an agent

result = client.call_tool("resolve_gtin", {"gtin": "00614141123452"})

if "error" in result:
    err = result["error"]
    code = err["code"]
    problem = err["data"]

    if problem.get("retryable"):
        # Optional: respect retry_after on rate-limit responses.
        time.sleep(problem.get("retry_after", 5))
        ...
    elif code == -32200:
        # Resource not found — surface to the user, do not retry.
        ...
    else:
        # 4xx-class user error or 5xx-class server error.
        ...
else:
    # Success path — use the tool's normal payload.
    ...

Reference

Tracking ticket: C-2491.
Implementation: backend/closient/mcp_errors.py.
REST counterpart: see Errors.

Getting Started

Developer Questions

User Guides

Technical Guides

MCP Server

Agent Skills

Compliance

Concepts

API Reference

Resources

MCP Error Contract

Envelope shape

Code table

Common errors per tool

Handling errors in an agent

Reference

​Envelope shape

​Code table

​Common errors per tool

​Handling errors in an agent

​Reference

Envelope shape

Code table

Common errors per tool

Handling errors in an agent

Reference