Error registry

By the end of this page you will know the shape of a Rail402 rejection, the guarantee it makes, how to branch on it in code, and the notable codes you are most likely to hit. This is the reference for @rail402.dev/errors, which the facilitator, the Bazaar, the MCP server, and the SDK all share.

The shape

Every rejection is a { code, reason, retryable } object.

{
  code: "mcp_budget_exceeded",
  reason: "The price is above the spend cap. Nothing was paid.",
  retryable: false
}

Field	Type	Meaning
`code`	`string`	A stable machine-readable identifier. Branch on this.
`reason`	`string`	A human-readable explanation. Never parse it in code.
`retryable`	`boolean`	Whether the same call may succeed on a retry.

The guarantee: every rejection across the facilitator, the Bazaar, and the MCP server carries a non-null reason. There is no null, empty, or missing reason anywhere. An agent can reason about a failure without parsing prose.

Handling errors

@rail402.dev/errors (also at @rail402.dev/sdk/errors) exports the registry and the helpers.

import { X402Error, isErrorCode, ERROR_REGISTRY, type ErrorCode } from "@rail402.dev/errors";

Export	What it is
`X402Error`	The error class carrying `{ code, reason, retryable }`.
`isErrorCode`	Narrows an unknown string to a known `ErrorCode`.
`ERROR_REGISTRY`	The full map from `ErrorCode` to its registry entry.
`ALL_ERROR_CODES`	The array of every known code.
`createError`	Builds a rejection from a registered code.
`enrichUpstreamCode`	Attaches a Rail402 reason to an upstream scheme code.
`ErrorCode`	The union type of every code.

The SDK’s buyer functions surface the same shape as result.error, so you branch on code the same way whether you caught an X402Error or read a Result.

const result = await payAndFetch(config, url, { maxAmount: "100000" });

if (!result.ok) {
  const { code, reason, retryable } = result.error;

  if (code === "config_no_signer") {
    // fix your config, this will never succeed on retry
  } else if (retryable) {
    // a transient condition, a retry may succeed
  } else {
    console.error(code, reason);
  }
}

Look up any code’s registered reason and retryability without triggering it:

if (isErrorCode(someString)) {
  const entry = ERROR_REGISTRY[someString]; // { reason, retryable, ... }
}

Retryable means retryable

retryable: true is reserved for genuinely transient conditions, such as rate limiting or a network submission failure. Everything else is false. Respect the flag. Retrying a non-retryable failure loops forever, and one code in particular means the money already moved, so a retry pays twice.

mcp_paid_but_resource_failed is not retryable. The payment settled and then the resource returned an error. The funds have already moved on chain. Do not retry. See Troubleshooting.

Notable codes

A small slice of the registry, covering the failures you meet first. Use ALL_ERROR_CODES and ERROR_REGISTRY to enumerate the full set at runtime.

Code	Meaning	Retryable
`config_no_signer`	No signing secret is configured, so nothing can be paid.	No
`mcp_budget_required`	A paying call was made without a spend cap. Nothing was paid.	No
`mcp_budget_exceeded`	The price is above the spend cap. Nothing was paid.	No
`invalid_exact_stellar_payload_authorization_replayed`	The authorization was already used. Sign a fresh one.	No
`invalid_exact_stellar_payload_missing_trustline_recipient`	The receiver has no trustline to the asset, so it cannot receive it.	No
`bazaar_mcp_resource_url_not_addressable`	The resource URL is `mcp://`, which has no addressable host. Use the HTTP endpoint.	No
`mcp_paid_but_resource_failed`	The payment settled, then the resource failed. The money moved. Do not retry.	No

Next steps

Troubleshooting

Symptom, cause, and fix for the common failures.

SDK reference

Where these codes surface in result.error.

FAQ

Answers to the questions behind many rejections.

Packages

Where the errors package fits.

Start here

Buyers & agents

Sellers

Operators

Concepts

Reference

Support

The shape

Handling errors

Retryable means retryable

Notable codes

Next steps

Troubleshooting

SDK reference

FAQ

Packages

​The shape

​Handling errors

​Retryable means retryable

​Notable codes

​Next steps

Troubleshooting

SDK reference

FAQ

Packages

The shape

Handling errors

Retryable means retryable

Notable codes

Next steps