Error Codes

All Deframe API errors follow a consistent JSON structure:

{
  "code": "QUOTE_NOT_FOUND",
  "message": "Quote not found or expired",
  "httpStatus": 404,
  "details": null
}

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

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
`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

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
`AMOUNT_IN_TOO_LOW`	400	`amountIn` is below the minimum threshold (1 USDC)	Increase the input amount
`AMOUNT_IN_TOO_HIGH`	400	`amountIn` exceeds the maximum threshold (3,000 USDC)	Reduce the input amount or contact support for higher limits

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

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

Code	HTTP Status	Description	Resolution
—	401	No API key provided	Include `x-api-key` header in your request
—	401	Invalid API key	Verify your API key at deframe.io
—	429	Rate limit exceeded	Wait for the retry window — see `retryAfter` in the response body

When you hit the rate limit, the response includes:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "details": {
      "retryAfter": 60
    }
  }
}

Use the retryAfter value (in seconds) before retrying. See Authentication for rate limit details.