Error Codes & Troubleshooting API v1

Error Response Format

All API errors return a JSON object with the following structure:

{
  "name": "Error",
  "message": "Error message",
  "code": 500
}

Field	Description
`name`	Always `"Error"`
`message`	Human-readable error description
`code`	HTTP status code (400, 500, etc.)

Use the message field to understand the specific error. The code field reflects the HTTP status code.

Common Errors

Token & Address Errors

Message	Solution
Unsupported `from` Token	Check `/tokens?hasCex=true` or `/tokens?hasDex=true` for supported tokens
Unsupported `to` Token	Check `/tokens?hasCex=true` or `/tokens?hasDex=true` for supported tokens
addressTo is invalid	Validate using `addressValidation` regex from `/chains`
addressFrom is invalid	Validate using `addressValidation` regex from `/chains`
`to` and `from` cannot be both the same token	From and To tokens only able to be the same token if private
Token not found	Token ID/symbol doesn’t exist
Network not found	Check `/chains` for supported networks
Address is not valid for this chain	Validate using `addressValidation` regex from `/chains`

Quote & Amount Errors

Message	Solution
Invalid Quote	Quote expired or invalid, request a new one
Path is invalid	Route not available, try different pair
`amount` is out of bounds for swap	Check `min` and `max` from quote response
Unable to perform exchange, quote over X USD	Reduce swap amount
Amount is too low, minimum is X USD	Increase swap amount
Could not retrieve price quotes	Try different amount or pair. For Private mode, try Standard

Order Errors

Message	Solution
Order not found	Verify `houdiniId` is correct
Swap not found	Swap ID doesn’t exist

Exchange & Routing Errors

Message	Solution
Unable to perform exchange, no available paths	Try different pair or amount
Unable to perform exchange, no available paths. Tip: try toggling OFF Exact mode	Disable fixed/exact mode
Unable to generate swap_hop_1 (anon)	Private routing failed - try Standard swap
Unable to generate swap_hop_2 (anon)	Private routing failed - try Standard swap

Authentication & Account Errors

Message	Solution
Please define your API key	Add `Authorization` header
Incorrect credentials	Verify API key and secret

Service Errors

Message	Solution
Something went wrong. Please contact support!	Retry or contact support
Your request has timed-out	Retry the request
Services temporary unavailable	Wait and retry
Anonymous exchanges are temporarily disabled	Use Standard swap or contact support

DEX-Specific Errors

Message	Solution
This chain is currently not supported	Check `/tokens?hasDex=true` for supported chains
Swap not supported	Pair not available for DEX swap

HTTP Status Codes

Status	Meaning	Common Causes
400	Bad Request	Invalid parameters, malformed JSON
401	Unauthorized	Missing or invalid API credentials
403	Forbidden	API key lacks permissions
404	Not Found	Resource doesn’t exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side issue
503	Service Unavailable	Maintenance or partner downtime

Need Help?

API v2 Reference

Complete endpoint documentation

Order Lifecycle

Understand order states

Quick Start

Integration guides for each swap type

Contact Support

Get help with specific issues

Overview

Swap Flow Guides

CEX Endpoints

DEX Endpoints

Utilities

Troubleshooting

Error Codes & Troubleshooting API v1

Error Response Format

Common Errors

Token & Address Errors

Quote & Amount Errors

Order Errors

Exchange & Routing Errors

Authentication & Account Errors

Service Errors

DEX-Specific Errors

HTTP Status Codes

Need Help?

API v2 Reference

Order Lifecycle

Quick Start

Contact Support

​Error Response Format

​Common Errors

​Token & Address Errors

​Quote & Amount Errors

​Order Errors

​Exchange & Routing Errors

​Authentication & Account Errors

​Service Errors

​DEX-Specific Errors

​HTTP Status Codes

​Need Help?

API v2 Reference

Order Lifecycle

Quick Start

Contact Support

Error Response Format

Common Errors

Token & Address Errors

Quote & Amount Errors

Order Errors

Exchange & Routing Errors

Authentication & Account Errors

Service Errors

DEX-Specific Errors

HTTP Status Codes

Need Help?