Error Codes - Pods API

All Pods API errors use one JSON envelope. The HTTP status line is the source of truth for the status code; the body is always:

{
  "error": {
    "code": "QUOTE_NOT_FOUND",
    "message": "Quote not found or expired"
  }
}

The details field is only present when there is extra structured context. For Zod validation failures (422), issues are in details.errors (path + message per field). Domain-specific data (for example needsSignUp) also lives under details.

Quote Errors

Code	HTTP Status	Description	Resolution
`QUOTE_NOT_FOUND`	404	Quote not found or expired	Request a new quote — quotes are valid for 5 minutes
`QUOTE_EXPIRED`	400	Quote has expired	Request a new quote using the same parameters
`QUOTE_GENERATION_FAILED`	400	Could not generate a quote for the specified parameters	Verify token addresses, chain names, and amount format
`QUOTE_VALIDATION_ERROR`	400	Quote validation failed	Check that `quoteId` and `rawQuote` match the original quote response

Swap Errors

Code	HTTP Status	Description	Resolution
`NO_ROUTE_FOUND`	400	No swap route available between the specified chains or tokens	Try a different token pair or check supported networks
`INVALID_PREFERRED_PROVIDER`	400	Unknown `preferredProvider` name on `GET /v2/swap/quote`	Use a registered provider id (`relay`, `mayan`, `lifi`, `cctp`, `1inch`, etc.)
`PREFERRED_PROVIDER_NOT_ELIGIBLE`	400	`preferredProvider` does not support this chain/token route	Omit the parameter or pick a provider eligible for the route
`PREFERRED_PROVIDER_QUOTE_UNAVAILABLE`	400	Eligible provider did not return a quote in time	Retry or omit `preferredProvider` to use the best available quote
`PROVIDER_NOT_FOUND`	404	Swap provider not found for the requested route	Use a supported chain and token combination
`BYTECODE_GENERATION_FAILED`	500	Failed to generate transaction bytecode	Retry the request — if the issue persists, contact support
`SWAP_EXECUTION_FAILED`	500	Failed to execute the swap transaction	Verify wallet balance, allowance, and gas fees

Validation Errors

Code	HTTP Status	Description	Resolution
`INVALID_AMOUNT_PARAMS`	400	Cannot specify both `amountIn` and `amountOut` simultaneously	Use only one of `amountIn` or `amountOut` per request
`MISSING_AMOUNT_PARAMS`	400	Either `amountIn` or `amountOut` is required	Include at least one amount parameter in the request
`INVALID_SLIPPAGE`	400	`slippage` must be between `0.0001` and `0.5` as a fraction of 1	Use a value like `0.01` for 1% slippage
`AMOUNT_IN_TOO_LOW_OFFRAMP`	400	Off-ramp `amountIn` must be greater than 1 USDC	Increase the input amount
`AMOUNT_IN_TOO_HIGH_OFFRAMP`	400	Off-ramp `amountIn` must be less than 5k USDC	Reduce the input amount or contact support for higher limits
`AMOUNT_OUT_TOO_LOW_OFFRAMP`	400	Off-ramp `amountOut` must be greater than 5 BRLA	Increase the output amount
`AMOUNT_OUT_TOO_HIGH_OFFRAMP`	400	Off-ramp `amountOut` must be less than 26k BRLA	Reduce the output amount or contact support for higher limits
`AMOUNT_IN_TOO_LOW_ONRAMP`	400	On-ramp `amountIn` must be greater than 5 BRLA	Increase the input amount
`AMOUNT_IN_TOO_HIGH_ONRAMP`	400	On-ramp `amountIn` must be less than 75k BRLA	Reduce the input amount or contact support for higher limits
`AMOUNT_OUT_TOO_LOW_ONRAMP`	400	On-ramp `amountOut` must be greater than 1 USDC	Increase the output amount
`AMOUNT_OUT_TOO_HIGH_ONRAMP`	400	On-ramp `amountOut` must be less than 15k USDC	Reduce the output amount or contact support for higher limits

Bridge Errors

Code	HTTP Status	Description	Resolution
`TRANSFER_VALIDATION_FAILED`	400	Token transfer validation failed	Verify the token address, chain, and transfer amount
`INSUFFICIENT_AMOUNT_FOR_REFUND`	400	Transferred amount is insufficient to cover the refund fee	Increase the transfer amount to cover bridge fees
`DEPOSIT_NOT_FOUND`	404	Bitcoin deposit not found	Wait for on-chain confirmation or check the deposit address

General Errors

Code	HTTP Status	Description	Resolution
`INTERNAL_SERVER_ERROR`	500	An unexpected error occurred	Retry the request — if the issue persists, contact support
`SYMBIOSIS_API_ERROR`	502	Error communicating with the Symbiosis bridge API	Retry after a short delay — this is usually transient

Authentication Errors

Code	HTTP Status	Description	Resolution
`AUTHENTICATION_REQUIRED`	401	No credentials provided, or API key used on a route that requires a Bearer token with a user role	Use `x-api-key` for API routes, or `Authorization: Bearer <token>` for customer dashboard routes
`INVALID_API_KEY`	401	API key is missing or not recognized	Verify your API key at pods.finance
`INVALID_AUTH_TOKEN`	401	Bearer token is invalid or expired	Refresh your Supabase or Magic session token
`VALIDATION_ERROR`	422	Request validation failed (e.g. malformed Authorization header on `GET /customers/me`)	Send `Authorization: Bearer <token>` in the correct format
—	401	No API key provided	Include `x-api-key` header in your request
—	429	Rate limit exceeded	Wait for the retry window — see `retryAfter` in the response body

Transaction Errors

Code	HTTP Status	Description	Resolution
`TX_NOT_FOUND`	404	Transaction hash not found on the specified chain	Verify the hash is correct, mined, and on the expected chain
`TX_NOT_MINED`	422	Transaction exists but is not yet mined	Wait for confirmation and retry
`TX_REVERTED`	422	Transaction was mined but reverted on-chain	Inspect the transaction on a block explorer

Rate Limit Response

When you hit a rate limit, the body matches the same envelope, for example:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests"
  }
}

Some endpoints also send a Retry-After response header (seconds). Prefer that header when present. See Authentication for rate limit details.

​Quote Errors

​Swap Errors

​Validation Errors

​Bridge Errors

​General Errors

​Authentication Errors

​Transaction Errors

​Rate Limit Response