> ## Documentation Index
> Fetch the complete documentation index at: https://docs.madra.finance/llms.txt
> Use this file to discover all available pages before exploring further.

# Error & Rejection Codes

> Every machine-readable rejection reason StellarX402 can return, in one place.

Every rejection an x402 payment can produce has a stable machine-readable code. Buyers, sellers, and agents can rely on the code without parsing the human message. This is the single source of truth. If you find a code returned in the wild that is not on this page, file it as a bug — an undocumented rejection is treated as a defect.

For how a buyer agent should react to each, see [Handling Rejections](/guides/buyers/handling-rejections).

## Codes returned by `/verify`

| Code                    | Meaning                                                | Category           |
| ----------------------- | ------------------------------------------------------ | ------------------ |
| `signature_invalid`     | The signed auth entries do not verify against `from`.  | Client bug         |
| `amount_mismatch`       | Signed amount does not equal `requirements.amount`.    | Client bug or race |
| `authorization_expired` | `validBefore` has passed.                              | Transient          |
| `insufficient_funds`    | `from` balance below `amount` in `asset`.              | Buyer budget       |
| `network_mismatch`      | Signed network differs from `requirements.network`.    | Configuration      |
| `asset_not_supported`   | Facilitator does not accept `asset`.                   | Configuration      |
| `unsupported_scheme`    | Facilitator does not implement `scheme`.               | Configuration      |
| `unsupported_version`   | `x402Version` outside the facilitator's supported set. | Configuration      |
| `payto_mismatch`        | Signed destination differs from `requirements.payTo`.  | Client bug         |
| `price_changed`         | Requirements changed between quote and verify.         | Transient          |
| `resource_gone`         | Seller has delisted the resource.                      | Terminal           |

## Codes returned by `/settle`

All `/verify` codes plus:

| Code                     | Meaning                                                                          | Category                      |
| ------------------------ | -------------------------------------------------------------------------------- | ----------------------------- |
| `amount_exceeds_ceiling` | `actualAmount` > `amount` on an upto settle.                                     | Seller bug                    |
| `settlement_failed`      | Chain submission rejected. `details.stellarError` carries the underlying reason. | Transient                     |
| `fee_ceiling_exceeded`   | Estimated fee above `SPONSOR_FEE_CEILING_XLM`.                                   | Transient                     |
| `sponsor_underfunded`    | Sponsor account cannot pay fees.                                                 | Operator incident             |
| `double_settle`          | Payload already settled. Response includes original `txHash`.                    | Retry artifact (not an error) |

## HTTP-level errors (not rejections)

These use the standard error envelope with HTTP 4xx/5xx, not the `isValid: false` shape:

| Code                 | HTTP | Meaning                                                |
| -------------------- | ---- | ------------------------------------------------------ |
| `bad_request`        | 400  | Malformed body or missing required field.              |
| `unknown_filter`     | 400  | Unrecognized query parameter on a discovery endpoint.  |
| `missing_query`      | 400  | `/discovery/search` called without `q`.                |
| `unauthorized`       | 401  | Missing or invalid bearer on an admin/seller endpoint. |
| `forbidden`          | 403  | Bearer valid but not entitled to this operation.       |
| `not_found`          | 404  | Path or resource id does not exist.                    |
| `rate_limited`       | 429  | Per-IP rate limit exceeded.                            |
| `internal_error`     | 500  | Unexpected server error. Reported to operators.        |
| `discovery_disabled` | 501  | Facilitator has `DISCOVERY_ENABLED=false`.             |

## Custom codes from lifecycle hooks

Sellers can reject payments from an `onVerify` [lifecycle hook](/advanced/lifecycle-hooks) with a code prefixed `custom_`. These are terminal from a buyer's perspective by convention. Document your custom codes in your own seller docs; buyers cannot introspect them.