Errors & retries
Separate transport failures, business results, and uncertain transaction outcomes.
Response envelope
{"code":0,"msg":"success","data":{}}{"code":3000,"msg":"no route available","data":null}Always inspect both the HTTP status and code. HTTP 200 with code 0 is success; HTTP 200 with a nonzero code is a business result. On failures, data is null and msg contains a short English reason. Retry decisions are based on HTTP status, with the documented EVM hash-only registration exception for code 2003.
Bounded quote retries
- Retry quotes only on HTTP 429 or 503. Do not automatically retry other statuses or HTTP 200 business failures.
- Honor Retry-After when present. Otherwise apply jittered backoff, for example 0.5–1.5 seconds.
- Allow at most two retries and cap total elapsed time, for example 15 seconds including the first attempt. If Retry-After exceeds the remaining budget, stop and ask the user to try later.
Error reference
| Code | HTTP | Meaning | Action |
|---|---|---|---|
| 1000 | 404 | Unknown path | Correct the endpoint. |
| 1001 | 413 | Body too large | Keep request bodies within 1 MiB. |
| 1002 | 500 | Internal error | Alert; do not automatically retry. |
| 1003 | 401 | Unauthorized | Check the API key. |
| 1004 | 429 | Rate limited | Honor Retry-After. |
| 1005 | 403 | Forbidden | Check the source IP allowlist. |
| 2001 | 200 | Invalid or missing parameter | Fix the parameter named by msg. |
| 2002 | 200 | Unsupported or disabled chain | Check chain and operation support. |
| 2003 | 200 | Transaction not found | For EVM hash-only registration, retry the same hash after a few seconds. |
| 2004 | 200 | Unsupported transaction | Use the returned ApproveManager transaction on contract chains. |
| 2005 | 200 | Broadcast definitely rejected | Nothing was stored. Request a new quote. |
| 2006 | 200 | Order not found | Check the order ID. |
| 2007 | 200 | Insufficient balance | Check token balance and native gas balance. |
| 2008 | 200 | Insufficient allowance | Approve the quoted spender and wait for confirmation. |
| 2009 | 200 | Simulation reverted | Inspect msg for the known revert reason. |
| 2010 | 200 | Signed gas limit too low | Use the quoted gas limit or estimate when absent. |
| 3000 | 200 | No route available | Do not automatically retry the same quote. |
| 3001 | 503 | Quote timed out | Retry quotes with bounded backoff. |
| 3002 | 503 | Provider unavailable, contract read failed, or contract paused | Retry quotes with bounded backoff. |
| 3003 | 503 | Chain node unavailable | Retry quotes with bounded backoff. |
| 3004 | 429 | Providers rate limited | Honor Retry-After. |
| 3005 | 500 | Service misconfigured | Alert; do not automatically retry. |
Operational handling
Alert on WaitVerify, any 500, and sustained 429/503 responses. Save the response X-Request-ID for support. Maintain your own order record with the aggregator orderId and source transaction hash.