Troubleshooting

Troubleshoot common Uniswap API request, quoting, authentication, and rate limit errors in swapping integrations.

The API is specific about request header validation. In particular, ensure that your accept and content-type headers only include the value application/json. For a complete example of properly formatted request headers, see the authentication section of the Developer Dashboard.

If you're sending the optional X-Agent-Info attribution header and it isn't being picked up, check the response for an x-agent-info-status: malformed header. See Agent Attribution for the full set of rules that make the header malformed. A malformed X-Agent-Info never causes an error response; the request proceeds without attribution.

Rate limits

Most API keys have a default rate limit of 6 requests per second (RPS). If you exceed the rate limit supported by an API key you can expect to receive an HTTP 429 error. If you receive a 429 error, we recommend pausing all requests from your API key and then retrying your requests. If you require a higher rate limit than what your API key is currently provisioned for, please reach out to our team through the Help Center. For more information on rate limits, see the Developer Dashboard.

Error Code Troubleshooting

404 No quotes available

The most commonly encountered HTTP error is an HTTP 404 from the /quote endpoint. The errorCode field identifies the cause, and detail carries a human-readable explanation:

{
  "errorCode": "QuoteAmountTooLowError",
  "detail": "Order size is below the minimum quotable size for the requested protocols on this chain.",
  "requestId": "..."
}

errorCode is a stable enum. detail is free text and may be reworded without notice. New errorCode values may be added over time, so treat unrecognized values the same as you do ResourceNotFound.

`errorCode`	What it means	What to do
`QuoteAmountTooLowError`	The `amount` is below the minimum quotable size for the requested protocols — most commonly UniswapX minimums on L2s (see UniswapX Chain Support)	Increase the amount, or widen `protocols`
`NoRouteFoundError`	Routing completed and found no viable route for this pair	Verify token addresses match the specified chain; do not retry unchanged
`UnsupportedTokenError`	A requested token is not routable (unknown or not on this chain)	Verify the token address belongs to the given chain (ex. USDC on Mainnet differs from Base)
`UnsupportedChainError`	The chain is not supported for this operation	See Supported Chains
`UniswapXNotSupportedOnChainError`	A UniswapX protocol was requested on a chain it does not serve	Remove the UniswapX protocol pin, or change chain
`UpstreamTimeoutError`	A routing dependency timed out or failed	Retry with exponential backoff — this is the only cause where an unchanged retry can succeed
`ResourceNotFound`	The failure could not be classified (`detail` is "No quotes available")	Retry cautiously; contact support with the `requestId` if persistent

A request that combines a bridge and a swap (different chains and different tokens) is not supported as a single quote and currently surfaces as ResourceNotFound. Request a bridge or a swap, not both — for bridgeable pairs see Supported Chains.

If an error persists after you apply the fix listed above, reach out to our team through the Help Center and include the requestId from the error response.

400 Request validation error

Request validation errors are returned when a request does not contain the minimum required set of fields or has other syntactical errors. Some examples are a required field is not populated (/quote requires type, amount, tokenInChainId, tokenOutChainId, tokenIn, tokenOut, and swapper), or an address is missing a character (eg. is 39 characters long instead of 40). These errors typically include a specific error message which describes the field which could not be interpreted.

400 Integrator fee errors

If something's off with your integratorFees, /quote returns a 400 with one of these errorCode values:

`errorCode`	What went wrong	How to fix it
`IntegratorFeesTooManyEntriesError`	You sent more than 4 fee entries	Send 4 or fewer
`IntegratorFeeEntryExceedsMaxError`	One entry is over 500 bips	Bring that entry down to 500 or less
`IntegratorFeesTotalExceedsMaxError`	The entries add up to more than 500 bips	Bring the total down to 500 or less
`InvalidIntegratorFeesError`	Something else is malformed: a repeated recipient, a zero or over-precise `bips`, or a sentinel address as a recipient	Check `detail`, it names the problem

Splitting fees across more than one entry also needs x-universal-router-version: 2.1.1 or higher. A lower version, or a chain that doesn't have 2.1.1 deployed yet, returns a 400.

Universal Router balance swap errors

A normal /quote can return a 200 without swapTransaction and leave it to /swap. A /quote or /swap with swapSource: "UNIVERSAL_ROUTER" doesn't do that: if we can't build the calldata, you get an error instead of a quote. A 400 means the request itself needs fixing. A 422 means the request was fine but we couldn't build a swap for it. Either way, detail tells you what happened.

Status	`detail`	What to do
400	`swapSource "UNIVERSAL_ROUTER" requires tokenInChainId to equal tokenOutChainId`	Quote on the destination chain only
400	`swapSource "UNIVERSAL_ROUTER" requires an EXACT_INPUT trade`	Use `EXACT_INPUT`
400	`autoSlippage is not supported with swapSource "UNIVERSAL_ROUTER"`	Send a `slippageTolerance` instead
400	`x-permit2-disabled is not supported with swapSource "UNIVERSAL_ROUTER"`	Drop the header; there's no permit in this flow
400	`recipient cannot be a Universal Router sentinel (address(1)/address(2)) or the zero address`	Put the end user's address in `swapper` (or `recipient`)
400	`wrap/unwrap pairs cannot be balance swapped; deliver the wrapped token directly`	Have your bridge deliver WETH
422	`permissioned tokens cannot be balance swapped`	Not supported in this mode
422	`no balance-swap route available for this pair`	Check the pair and chain; retrying unchanged won't help
422	`the routed swap failed simulation; no balance-swap calldata is served for a known-failing route`	The swap reverted in simulation. Re-quote, or re-quote without `swapSource` to see `txFailureReasons`
422	`the routed path cannot be executed from the router balance; re-quote without swapSource`	The route spends raw ETH in a v4 pool. Re-quote without `swapSource`, or deliver WETH

Two simulation failures don't trigger the 422: TRANSFER_FROM_FAILED and SLIPPAGE_TOO_LOW. Those quotes still come back with calldata. The integration guide explains why.

401 Unauthorized error

All API requests must be authenticated through the inclusion of a valid API key in the header of the request. If you do not have an API key, you may create one through the Uniswap Developer Platform. 401 errors may also be returned if the request has malformed or missing required headers, or if headers contain unsupported values (see above). For more details on authentication requirements, see the Developer Dashboard.

For developer support, reach out to our team through the Help Center.

Common Issues

Headers