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

# Failure handling

> What the transfers service does when a chain, a provider or a user does something unexpected.

| Failure | Behaviour |
| - | - |
| The quote expires before anything irreversible | `EXPIRED`. The funds stay in the user's wallet and can fund a new transfer. |
| Too little sent to a deposit address | The transfer waits until expiry. |
| Too much sent to a deposit address | Only the quoted amount moves. |
| The deposit address balance drops before expiry | `MANUAL_REVIEW`, not expiry, because a burn may be unsubmitted. The nightly reconciliation finds the burn and resumes at `SOURCE_SIGNED`. |
| A submit result is unknown | The worker looks up the hash first. Each transfer has one irreversible step, guarded by a unique source transaction and a state check. |
| Iris is slow or rate-limited | Back off below Circle's 40 requests per second. Never burn again. |
| A third party relays the CCTP mint first | The nonce check skips Pesa's submit. The arrival is still recorded. |
| LayerZero delivery is slow | Tracked by GUID. Never sent again. |
| A trustline is missing at delivery | `PENDING_TRUST`. Sponsored onboarding restores it, then the mint or delivery is retried. |
| The swap price moved | `SWAP_REQUOTE`. The USDT0 stays in the user's wallet until they approve a fresh quote. |
| A relayer or the relay is low on fees | That chain's routes report `available: false`. Open transfers wait. |
| Invalid withdrawal address | Refused at quote time, before any signature. |
| A payout matches no transfer | Stored once as an orphan observation for manual review. Never credited. |
| Circle or Tether freezes an address | `MANUAL_REVIEW`. |
| The worker restarts | It re-reads every open row. Every step is idempotent. |

## Reconciliation

A nightly job checks the books:

* Every `CREDITED` deposit has a source receipt, a provider confirmation (Iris or LayerZero) and a Stellar arrival for the same amount.
* Every `DELIVERED` withdrawal has a Stellar debit and a destination receipt.
* Relayer and relay balances are reported per chain.

Each run writes a report. Any mismatch is a finding in that report.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.