Error Codes

This page documents the error responses you may encounter when using the Squid API. Understanding these errors will help you build robust error handling into your integration.

---

HTTP Error Responses

HTTP Status	Type	Description
400	BAD_REQUEST	Invalid or missing request parameters
401	UNAUTHORIZED	Missing or invalid x-integrator-id header
404	NOT_FOUND	Resource not found (e.g., unknown transaction ID)
429	RATE_LIMITED	Too many requests — see Rate Limiting
500	INTERNAL_ERROR	Server-side error — retry with backoff

---

Route Request Errors

These errors are returned by the POST /v2/route endpoint:

Error Message	Cause	Resolution
x-integrator-id header is missing	Request missing the required auth header	Add the x-integrator-id header to every request
Too many quote requests for this address	Duplicate quoteOnly: false request for the same wallet	Wait retryAfter seconds, or use quoteOnly: true for price display
No route found	No valid route exists for the given parameters	Check that source/destination chains and tokens are supported. Verify sufficient liquidity exists.
Amount too low	The fromAmount is below the minimum for the route	Increase the swap amount
Amount too high	The fromAmount exceeds the maximum for the route	Decrease the swap amount
Unsupported chain	The specified chain ID is not supported	Check the supported chains list
Unsupported token	The specified token address is not whitelisted	Verify the token address. Only whitelisted tokens are supported.

Example: Unsupported Token

{
    "message": "Token is not supported for toChain: 8453 toToken: 0xeeeeeeseeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee.",
    "statusCode": 400,
    "type": "BAD_REQUEST"
}

Example: Unsupported Chain

{
    "message": "toChain: 84353 unsupported chain id",
    "statusCode": 400,
    "type": "SCHEMA_VALIDATION_ERROR"
}

---

Status API Errors

These errors are returned by the GET /v2/status endpoint:

HTTP Status	Scenario	Resolution
404	Transaction not yet indexed	Retry after 5 seconds. Indexing typically takes 5–10 seconds after execution. Some chains (e.g., Filecoin) take longer.
400	Missing required parameters	Ensure transactionId, fromChainId, toChainId, and quoteId are provided.

---

Transaction Status Values

After a transaction is submitted, the status API returns a squidTransactionStatus field. See Track Status for details on each status:

Status	Description
success	Transaction completed on all chains
ongoing	Transaction in progress — no action needed
needs_gas	Gas price spike on destination chain (Axelar routes only)
partial_success	Source chain executed but destination reverted
not_found	Transaction not yet indexed — retry shortly
refund	Squid Intents route failed — funds refunded on source chain (~10 min)

---

Best Practices

1. Always check the HTTP status code before parsing the response body.

2. Log the full error response — Squid error payloads include descriptive messages.

3. Use quoteOnly: true for price discovery to avoid rate limit errors.