Documentation Index
Fetch the complete documentation index at: https://docs.deframe.io/llms.txt
Use this file to discover all available pages before exploring further.
All Deframe 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"
}
}
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 |
|---|
| — | 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 |
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"
}
}
Retry-After response header (seconds). Prefer that header when present. See Authentication for rate limit details.
