> ## Documentation Index
> Fetch the complete documentation index at: https://docs.houdiniswap.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Error Codes & Troubleshooting
> Complete reference of error codes, HTTP statuses, and response formats for the HoudiniSwap Partner API v2.
## Response Format
All v2 error responses follow this shape:
```json theme={null}
{
"code": "QUOTE_OVER_LIMIT",
"message": "Unable to perform exchange, quote over 100000 USD",
"requestId": "94eb4a6f-12ca-4f22-9d0c-7ffd65ace1c7"
}
```
| Field | Type | Description |
| ----------- | ------ | ----------------------------------------------------------------------------- |
| `code` | string | Machine-readable error code (stable enum value). **Match on this field.** |
| `message` | string | Human-readable description. May contain dynamic values — use regex if needed. |
| `requestId` | string | Unique request identifier for support/debugging. |
Always match on the `code` string, not the HTTP status or message text. The `code` values are a stable enum and won't change without a breaking version bump.
### Special Response Shapes
**Validation errors** include a `fields` object with per-field details:
```json theme={null}
{
"code": "VALIDATION_ERROR",
"message": "Validation Failed",
"requestId": "...",
"fields": {
"amount": {
"message": "Amount must be positive",
"value": -5
}
}
}
```
**Rate limit errors** include retry metadata:
```json theme={null}
{
"code": "RATE_LIMIT_EXCEEDED",
"message": "FREE tier: 20 quote requests per minute. Try again in 45 seconds.",
"requestId": "...",
"retryAfter": 45,
"meta": {
"retryAfter": 45,
"limit": 20,
"windowType": "minute",
"operationType": "quote",
"tier": "free"
}
}
```
***
## Error Codes by Endpoint
### `GET /v2/quotes`
| HTTP | Code | Message | Notes |
| ---- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| 422 | `VALIDATION_ERROR` | Validation Failed | Missing/invalid params. Includes `fields` object. |
| 422 | `QUOTE_OVER_LIMIT` | Unable to perform exchange, quote over {maxUSD} USD | Dynamic max value. |
| 422 | `AMOUNT_TOO_LOW` | Amount is too low, minimum is {minUSD} USD | Dynamic min value. |
| 422 | `UNSUPPORTED_FROM_TOKEN` | Unsupported \`from\` Token | Token ID not found or disabled. |
| 422 | `UNSUPPORTED_TO_TOKEN` | Unsupported \`to\` Token | Token ID not found or disabled. |
| 422 | `TO_AND_FROM_CANNOT_BE_THE_SAME` | \`to\` and \`from\` cannot be both the same token | |
| 422 | `UNSUPPORTED_ANON_TOKEN` | Unsupported \`anonymousToken\` | Invalid intermediary token for private quotes. |
| 422 | `SWAP_AMOUNT_IS_OUT_OF_BOUNDS` | `amount` is out of bounds for swap from {from} | Provider-level min/max exceeded. |
| 422 | `XMR_SWAP_AMOUNT_IS_OUT_OF_BOUNDS` | `amount` is out of bounds for ANON\_TOKEN swap to {to} | Private swap intermediary bounds exceeded. |
| 429 | `RATE_LIMIT_EXCEEDED` | {tier} tier: {limit} quote requests per {window} . Try again in {retryAfter} seconds. | Includes `retryAfter` and `meta`. |
| 503 | `PRICE_QUOTES_NOT_RETRIEVED` | Could not retrieve price quotes. Try to use a different amount or a different pair. If using Private mode, try Semi-Private | All providers failed to return quotes. |
| 503 | `ANONYMOUS_DISABLED` | Anonymous exchanges are temporarily disabled. Please contact support for more details! | Feature flag is off. |
| 500 | `INTERNAL_SERVER_ERROR` | Internal Server Error | Catch-all for unexpected errors. |
### `POST /v2/exchanges`
| HTTP | Code | Message | Notes |
| ---- | ----------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| 422 | `VALIDATION_ERROR` | Validation Failed | Missing/invalid body fields. Also: expired quote (message includes max age). |
| 422 | `INVALID_QUOTE` | Invalid Quote | Quote not found, expired, or wrong type. |
| 422 | `INVALID_PATH` | Path is invalid | The swap route/path from the quote is invalid or unavailable. |
| 422 | `ADDRESS_TO_INVALID` | addressTo is invalid | Generic address validation failure. |
| 422 | `ADDRESS_TO_INVALID_FOR_CHAIN` | addressTo is invalid for {chain} | Chain-specific address validation failure. |
| 422 | `ADDRESS_FROM_INVALID` | addressFrom is invalid | Missing or invalid source address (required for DEX). |
| 422 | `ADDRESS_FROM_INVALID_FOR_CHAIN` | address {type} is invalid for {chain} | Chain-specific source address validation failure. `{type}` is "from" or "to". |
| 422 | `ADDRESS_TO_IN_DEPOSIT_LOG` | addressTo cannot be used as it exists in deposit log | Address reuse prevention. |
| 422 | `ADDRESS_TO_IS_TOKEN_ADDRESS` | addressTo cannot be a token contract address | Sending to a contract address is blocked. |
| 422 | `X_ADDRESS_NOT_SUPPORTED` | X-Address not supported yet! | XRP X-format addresses not supported. |
| 422 | `REUSED_DEPOSIT_ADDRESS` | Reused Deposit Address: {addressFrom} memo: {senderTag} swap: {swap} | Deposit address collision detected. |
| 422 | `SWAP_AMOUNT_IS_OUT_OF_BOUNDS` | `amount` is out of bounds for swap from {from} | Provider-level bounds exceeded at exchange time. |
| 422 | `XMR_SWAP_AMOUNT_IS_OUT_OF_BOUNDS` | `amount` is out of bounds for ANON\_TOKEN swap to {to} | Private swap intermediary bounds exceeded. |
| 422 | `TOKEN_DISABLED` | Token with ID {tokenId} is disabled | Token was disabled between quote and exchange. |
| 422 | `INVALID_SWAP` | Invalid swap type: {swap} | Unknown or disabled swap provider. |
| 422 | `ORDER_ALREADY_INITIALIZING_OR_PROCESSED` | Order already INITIALIZING or processed | Duplicate exchange attempt. |
| 422 | `REFUND_ADDRESS_REQUIRED_FOR_FIXED_RATE` | Refund address is required for fixed rate exchanges | `refundAddress` was omitted when using a `fixed=true` quote. Always include it for fixed rate orders. |
| 422 | `FIXED_RATE_QUOTE_EXPIRED` | Fixed rate quote has expired | `validUntil` has passed, or the provider lost fixed-rate capability after the quote was issued. Re-fetch a new quote. |
| 422 | `ANONYMOUS_AND_FIXED_RATE_NOT_SUPPORTED` | Anonymous and fixed rate are not supported together | Cannot combine `fixed=true` with private/anonymous routing. Use a standard quote instead. |
| 422 | `DEX_AND_FIXED_RATE_NOT_SUPPORTED` | DEX and fixed rate are not supported together | Cannot use `fixed=true` with DEX quotes. Fixed rate is only available for standard (CEX) swaps. |
| 429 | `RATE_LIMIT_EXCEEDED` | (same pattern as quotes) | Includes `retryAfter` and `meta`. |
| 500 | `UNABLE_TO_PERFORM_EXCHANGE` | Unable to perform exchange, no available paths | All providers failed during execution. |
| 503 | `ANONYMOUS_DISABLED` | Anonymous exchanges are temporarily disabled... | Feature flag is off. |
| 404 | `NOT_FOUND` | Not found | Post-creation order lookup failed (edge case). |
| 500 | `INTERNAL_SERVER_ERROR` | Internal Server Error | Catch-all. |
### `GET /v2/orders/{houdiniId}` and `GET /v2/orders`
| HTTP | Code | Message | Notes |
| ---- | ----------------------- | --------------------- | ------------------------------------------------------ |
| 404 | `NOT_FOUND` | Not found | Order doesn't exist or belongs to a different partner. |
| 422 | `VALIDATION_ERROR` | Validation Failed | Invalid query parameters. |
| 429 | `RATE_LIMIT_EXCEEDED` | (same pattern) | |
| 500 | `INTERNAL_SERVER_ERROR` | Internal Server Error | Catch-all. |
### Global Errors (all endpoints)
These can be returned by any endpoint:
| HTTP | Code | Message | Notes |
| ---- | -------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| 400 | `MISSING_API_CREDENTIALS` | Missing API credentials | No `Authorization` header or `partner-id` header provided. |
| 400 | `INVALID_API_CREDENTIALS_FORMAT` | Invalid API credentials format | `Authorization` header is malformed (expected `id:secret`). |
| 401 | `INVALID_API_CREDENTIALS` | Invalid API credentials | Credentials don't match any active partner. |
| 401 | `AUTHENTICATION_FAILED` | Authentication failed | Auth check threw an unexpected error. |
| 401 | `INVALID_SECURITY_SCHEME` | Invalid security scheme | Request used an unsupported authentication method. Internal safeguard — should not occur in normal usage. |
| 403 | `ACCESS_DENIED` | Access restricted for partner-id requests | Operation not allowed for public `partner-id` access. |
| 404 | `ROUTE_NOT_FOUND` | Route not found | The requested URL path doesn't match any v2 endpoint. |
| 429 | `RATE_LIMIT_EXCEEDED` | (dynamic — see special shape above) | Per-partner, per-operation rate limits. |
| 503 | `SERVICE_UNAVAILABLE` | Service Unavailable | Backend service is temporarily unavailable. |
| 500 | `INTERNAL_SERVER_ERROR` | Internal Server Error | Unhandled exception. |
***
## HTTP Status Summary
| Status | Meaning | Code Strings |
| ------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | Bad Request | `MISSING_API_CREDENTIALS`, `INVALID_API_CREDENTIALS_FORMAT` |
| 401 | Unauthorized | `INVALID_API_CREDENTIALS`, `AUTHENTICATION_FAILED`, `INVALID_SECURITY_SCHEME` |
| 403 | Forbidden | `ACCESS_DENIED` |
| 404 | Not Found | `NOT_FOUND`, `ROUTE_NOT_FOUND` |
| 422 | Unprocessable Entity | `VALIDATION_ERROR`, `QUOTE_OVER_LIMIT`, `AMOUNT_TOO_LOW`, `UNSUPPORTED_FROM_TOKEN`, `UNSUPPORTED_TO_TOKEN`, `TO_AND_FROM_CANNOT_BE_THE_SAME`, `UNSUPPORTED_ANON_TOKEN`, `SWAP_AMOUNT_IS_OUT_OF_BOUNDS`, `XMR_SWAP_AMOUNT_IS_OUT_OF_BOUNDS`, `ADDRESS_TO_INVALID`, `ADDRESS_TO_INVALID_FOR_CHAIN`, `ADDRESS_FROM_INVALID`, `ADDRESS_FROM_INVALID_FOR_CHAIN`, `ADDRESS_TO_IN_DEPOSIT_LOG`, `ADDRESS_TO_IS_TOKEN_ADDRESS`, `X_ADDRESS_NOT_SUPPORTED`, `REUSED_DEPOSIT_ADDRESS`, `TOKEN_DISABLED`, `INVALID_SWAP`, `ORDER_ALREADY_INITIALIZING_OR_PROCESSED`, `INVALID_QUOTE`, `INVALID_PATH`, `REFUND_ADDRESS_REQUIRED_FOR_FIXED_RATE`, `FIXED_RATE_QUOTE_EXPIRED`, `ANONYMOUS_AND_FIXED_RATE_NOT_SUPPORTED`, `DEX_AND_FIXED_RATE_NOT_SUPPORTED` |
| 429 | Too Many Requests | `RATE_LIMIT_EXCEEDED` |
| 500 | Internal Server Error | `INTERNAL_SERVER_ERROR`, `UNABLE_TO_PERFORM_EXCHANGE` |
| 503 | Service Unavailable | `SERVICE_UNAVAILABLE`, `PRICE_QUOTES_NOT_RETRIEVED`, `ANONYMOUS_DISABLED` |
***
## Best Practices
1. **Match on `code`, not `message`** — The `code` field is a stable string enum. Messages may contain dynamic values and can change without notice.
2. **Use regex for dynamic messages** — For codes like `QUOTE_OVER_LIMIT`, `AMOUNT_TOO_LOW`, `SWAP_AMOUNT_IS_OUT_OF_BOUNDS`, extract the dynamic part with a regex:
```text theme={null}
/Unable to perform exchange, quote over (\d+) USD/
/Amount is too low, minimum is ([\d.]+) USD/
```
3. **Handle 422 as your primary error status** — Most business logic errors return 422, not 400 or 500.
4. **Respect `retryAfter`** — On 429 responses, wait the specified number of seconds before retrying. The `meta` object provides additional context about which limit was hit.
5. **Log `requestId`** — Always log the `requestId` from error responses. Include it when contacting support for faster debugging.
6. **Implement exponential backoff for 500/503** — These are transient errors. Retry with backoff (e.g. 1s, 2s, 4s) up to 3 attempts.
7. **Don't retry 422 errors** — These are deterministic. The same request will produce the same error. Fix the input before retrying.
## Need Help?
Complete endpoint documentation
Understand order states
Integration guides for each swap type
Get help with specific issues