Overview

Errors

One error envelope, eighteen typed codes, and which of them are worth retrying.

Every surface maps failures to the same typed codes. Over HTTP the error body is this envelope; over MCP it is the tool result's content with isError: true; over A2A it is the artifact of a failed task.

Error envelopejson

{
  "status": "error",
  "code": "INPUT_INVALID",
  "message": "…",
  "retryable": false,
  "requestId": "…",
  "resourceId": "basic_weather"
}

status"error"required

codeCommerceErrorCoderequired

One of the codes below. Stable — safe to branch on.

messagestringrequired

Human-readable. Stack traces and internal messages never cross the boundary.

retryablebooleanrequired

Whether the same request may reasonably be retried.

requestId / resourceIdstring

Correlation identifiers, when known.

detailsobject

Client-safe extra context. After a settled payment whose delivery failed, it carries the payment summary.

Codes

Code	HTTP	Retry	Meaning
`CONFIG_INVALID`	500	no	the configuration is invalid
`RESOURCE_NOT_FOUND`	404	no	no such resource, or not exposed on this surface
`INPUT_INVALID`	400	no	input failed the resource's schema, or a path parameter was empty, . or ..
`PAYMENT_REQUIRED`	402	no	a paid resource was called without a proof
`PAYMENT_INVALID`	402	no	malformed, wrong amount, recipient, network, asset, expired or underfunded
`PAYMENT_REPLAYED`	409	no	this authorisation was already used
`PAYMENT_PROVIDER_UNAVAILABLE`	503	yes	the payment rail or RPC is unreachable
`PAYMENT_SETTLEMENT_FAILED`	502	no	the settlement transaction failed
`AUTHORIZATION_REQUIRED`	403	no	the resource requires an AP2 mandate
`AUTHORIZATION_INVALID`	403	no	the mandate failed verification
`AUTHORIZATION_REPLAYED`	409	no	the mandate was already spent
`AUTHORIZATION_PROVIDER_UNAVAILABLE`	503	yes	the verifier or its store failed
`BACKEND_TIMEOUT`	504	yes	the merchant backend did not answer in time
`BACKEND_ERROR`	502	no	the backend failed, redirected, or answered too much
`PROTOCOL_UNSUPPORTED`	501	no	the operation is not implemented
`GATEWAY_BUSY`	503	yes	load shedding — back off and retry
`STORAGE_ERROR`	500	no	the receipt store failed
`INTERNAL_ERROR`	500	no	anything else; no internals are disclosed

Why authorization failures are 403, not 402A 402 tells a client “pay and retry”, which cannot fix a missing or rejected mandate — and a client that auto-pays on 402 would be charged for a request that was never going to be delivered.

Payment required is not an error

An unpaid call to a paid resource returns 402 with a status: "payment-required" envelope instead — see Invoke a resource.

Errors

#Codes

#Payment required is not an error

Codes

Payment required is not an error