Error & retry guide
Error codes, causes, and retry strategies.
Error reference
HTTP / ok | Likely cause | Recommended action |
|---|---|---|
400 / ok:false | Invalid request shape | Fix the JSON, check fromDecimals, toDecimals, chain |
401 / Invalid or revoked API key | Bad/missing key or rate limit | Check X-ORKID-API-Key header, request a key rotation |
403 / Missing anti-scraping token | Browser request without page token | Use an API key instead |
200 / error: "Swap too small..." | Below gasless minimum | Increase amount or set dryRun: true and have user pay gas |
200 / error: "Gas estimation failed" | Permit/signature/calldata will revert | Check token approval, nonce, spender, chain, token addresses, balance |
200 / error: "Invalid nonce" | Nonce already used | Call findUnusedNonce again |
200 / error: "TRANSFER_FROM_FAILED" | Insufficient allowance or balance | Check token.approve(PERMIT2, ...) and balanceOf |
200 / error: "Price impact too high..." | Slippage exceeds max (500 bps) | Try a smaller amount or a different token pair |
Retry rules
- Retry
5xxup to 3 times with exponential backoff. - Do not blindly retry a successful
/solve(ok: true) — it may have already submitted. - For
dryRun: false, if the solver returnsok: truewithtransaction.txHash, the swap is submitted. - For
dryRun: true, cache the returneddataand submit it withsendTransactiononly once. - In the sandbox, retries are safe — no transaction is ever submitted.
Common issues
Gas estimation failed
This usually means the Permit2 signature, nonce, or spender is wrong. Check:
- The
spenderin the signed message matches the TVMExecutor for the target chain. - The token is approved to Permit2 (
0x000000000022D473030F116dDEE9F6B43aC78BA3). - The nonce hasn't been used (read the nonce bitmap on-chain).
- The user has sufficient balance of the input token.
- The
deadlinein the permit hasn't passed.
Price impact too high
The solver rejects swaps with price impact above 500 bps (5%). Try a smaller amount or a different token pair with deeper liquidity.
Swap too small for gasless
Each chain has a minimum notional for gasless execution (the solver pays gas). Below that, the swap still works but the user pays gas. See minimum notional.