Common API categories
| Category | User-facing response |
|---|---|
| Quote expired | Ask the user to refresh the quote and try again. |
| Quote already consumed | Fetch a new quote; never retry with the same one. |
| Amount mismatch | Rebuild the order from a fresh quote. |
| Duplicate commitment | Generate a fresh secret and commitment hash. |
| Unsupported route | Show the pair as unavailable and let the user choose another route. |
| Watcher delay | Keep polling and show the latest transaction hash. |
| Relayer accepted | Show pending; 202 Accepted does not mean mined. |
Claim failures
| Error shape | Likely cause | Next step |
|---|---|---|
| Invalid secret | Secret does not match the commitment hash. | Regenerate flow from the saved swap secret, not a new random value. |
| Vault missing | The destination side has not been initiated yet. | Keep polling or show solver delay. |
| Already settled | The side may already be claimed or cancelled. | Refresh order state and chain status. |
| Hop signature invalid | The signed hop payload does not match the route. | Rebuild from current order route data and re-sign. |