> ## 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.

# Handling Rejections & Error Codes

> How an agent should react to each machine-readable payment rejection so failures do not loop.

An agent that treats every payment failure the same way is an agent that either gives up too easily or burns money in a loop. This page maps every rejection code to a sensible reaction. For the wire-level definitions, see the [Error & Rejection Codes reference](/reference/error-codes).

## Reaction table

| Code                    | What it means                                      | What to do                                                           |
| ----------------------- | -------------------------------------------------- | -------------------------------------------------------------------- |
| `insufficient_funds`    | Wallet balance below required amount               | Top up. Do not retry the same request until balance changes.         |
| `authorization_expired` | `validBefore` elapsed before verify                | Re-sign with a fresh authorization and retry once.                   |
| `amount_mismatch`       | Signed amount does not match `PaymentRequirements` | Re-fetch `PaymentRequirements` (price may have changed) and re-sign. |
| `price_changed`         | Server changed its price between quote and verify  | Re-fetch and re-quote.                                               |
| `network_mismatch`      | Signed on wrong network                            | Fix wallet network. Not usually a transient error.                   |
| `asset_not_supported`   | Facilitator does not settle in this asset          | Do not retry. Choose another provider.                               |
| `resource_gone`         | Endpoint is deprecated or removed                  | Drop from the queue. Do not retry.                                   |
| `rate_limited`          | Facilitator or seller throttling                   | Back off with jitter.                                                |
| `settlement_failed`     | On-chain submission failed                         | Retry after a short delay. If it persists, escalate.                 |
| `signature_invalid`     | Client bug or wrong key                            | Do not retry. Fix client.                                            |
| `unsupported_scheme`    | Facilitator does not support the scheme requested  | Choose another provider.                                             |

## Idempotency

`fetchWithPayment` treats each attempt as independent. If you retry after a rejection, you sign a new authorization; the previous one is discarded, not "redeemed."

## What to log

At minimum, log the tuple `(resource, code, amount, txHash?)`. Aggregating on `code` per-resource lets you spot degraded endpoints before your budget notices.

## Backoff policy

A reasonable default:

* Transient (`settlement_failed`, `rate_limited`): exponential backoff, 3 attempts, jitter.
* Client-fixable (`amount_mismatch`, `price_changed`, `authorization_expired`): 1 immediate retry, then give up.
* Terminal (`resource_gone`, `asset_not_supported`, `signature_invalid`, `unsupported_scheme`, `network_mismatch`): no retry.
* Budget (`insufficient_funds`): no retry until the wallet's balance changes.