> ## Documentation Index > Fetch the complete documentation index at: https://docs.pods.finance/llms.txt > Use this file to discover all available pages before exploring further. # Error Codes > Complete reference for all Pods API error codes, HTTP status codes, and resolution guidance 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: ```json theme={null} { "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 ` for customer dashboard routes | | `INVALID_API_KEY` | 401 | API key is missing or not recognized | Verify your API key at [pods.finance](https://www.pods.finance/plg/select-plan) | | `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 ` 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: ```json theme={null} { "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](/getting-started/authentication) for rate limit details.