Skip to main content

​
Response Format

All v2 error responses follow this shape: 
{
  "code": "QUOTE_OVER_LIMIT",
  "message": "Unable to perform exchange, quote over 100000 USD",
  "requestId": "94eb4a6f-12ca-4f22-9d0c-7ffd65ace1c7"
}
FieldTypeDescription
codestringMachine-readable error code (stable enum value). Match on this field.
messagestringHuman-readable description. May contain dynamic values — use regex if needed.
requestIdstringUnique 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: 
{
  "code": "VALIDATION_ERROR",
  "message": "Validation Failed",
  "requestId": "...",
  "fields": {
    "amount": {
      "message": "Amount must be positive",
      "value": -5
    }
  }
}
Rate limit errors include retry metadata: 
{
  "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

HTTPCodeMessageNotes
422VALIDATION_ERRORValidation FailedMissing/invalid params. Includes fields object.
422QUOTE_OVER_LIMITUnable to perform exchange, quote over USDDynamic max value.
422AMOUNT_TOO_LOWAmount is too low, minimum is USDDynamic min value.
422UNSUPPORTED_FROM_TOKENUnsupported `from` TokenToken ID not found or disabled.
422UNSUPPORTED_TO_TOKENUnsupported `to` TokenToken ID not found or disabled.
422TO_AND_FROM_CANNOT_BE_THE_SAME`to` and `from` cannot be both the same token
422UNSUPPORTED_ANON_TOKENUnsupported `anonymousToken`Invalid intermediary token for private quotes.
422SWAP_AMOUNT_IS_OUT_OF_BOUNDSamount is out of bounds for swap from Provider-level min/max exceeded.
422XMR_SWAP_AMOUNT_IS_OUT_OF_BOUNDSamount is out of bounds for ANON_TOKEN swap to Private swap intermediary bounds exceeded.
429RATE_LIMIT_EXCEEDED tier: quote requests per . Try again in seconds.Includes retryAfter and meta.
503PRICE_QUOTES_NOT_RETRIEVEDCould not retrieve price quotes. Try to use a different amount or a different pair. If using Private mode, try Semi-PrivateAll providers failed to return quotes.
503ANONYMOUS_DISABLEDAnonymous exchanges are temporarily disabled. Please contact support for more details!Feature flag is off.
500INTERNAL_SERVER_ERRORInternal Server ErrorCatch-all for unexpected errors.

​
POST /v2/exchanges

HTTPCodeMessageNotes
422VALIDATION_ERRORValidation FailedMissing/invalid body fields. Also: expired quote (message includes max age).
422INVALID_QUOTEInvalid QuoteQuote not found, expired, or wrong type.
422INVALID_PATHPath is invalidThe swap route/path from the quote is invalid or unavailable.
422ADDRESS_TO_INVALIDaddressTo is invalidGeneric address validation failure.
422ADDRESS_TO_INVALID_FOR_CHAINaddressTo is invalid for Chain-specific address validation failure.
422ADDRESS_FROM_INVALIDaddressFrom is invalidMissing or invalid source address (required for DEX).
422ADDRESS_FROM_INVALID_FOR_CHAINaddress is invalid for Chain-specific source address validation failure. {type} is “from” or “to”.
422ADDRESS_TO_IN_DEPOSIT_LOGaddressTo cannot be used as it exists in deposit logAddress reuse prevention.
422ADDRESS_TO_IS_TOKEN_ADDRESSaddressTo cannot be a token contract addressSending to a contract address is blocked.
422X_ADDRESS_NOT_SUPPORTEDX-Address not supported yet!XRP X-format addresses not supported.
422REUSED_DEPOSIT_ADDRESSReused Deposit Address: memo: swap: Deposit address collision detected.
422SWAP_AMOUNT_IS_OUT_OF_BOUNDSamount is out of bounds for swap from Provider-level bounds exceeded at exchange time.
422XMR_SWAP_AMOUNT_IS_OUT_OF_BOUNDSamount is out of bounds for ANON_TOKEN swap to Private swap intermediary bounds exceeded.
422TOKEN_DISABLEDToken with ID is disabledToken was disabled between quote and exchange.
422INVALID_SWAPInvalid swap type: Unknown or disabled swap provider.
422ORDER_ALREADY_INITIALIZING_OR_PROCESSEDOrder already INITIALIZING or processedDuplicate exchange attempt.
429RATE_LIMIT_EXCEEDED(same pattern as quotes)Includes retryAfter and meta.
500UNABLE_TO_PERFORM_EXCHANGEUnable to perform exchange, no available pathsAll providers failed during execution.
503ANONYMOUS_DISABLEDAnonymous exchanges are temporarily disabled…Feature flag is off.
404NOT_FOUNDNot foundPost-creation order lookup failed (edge case).
500INTERNAL_SERVER_ERRORInternal Server ErrorCatch-all.

​
GET /v2/orders/{houdiniId} and GET /v2/orders

HTTPCodeMessageNotes
404NOT_FOUNDNot foundOrder doesn’t exist or belongs to a different partner.
422VALIDATION_ERRORValidation FailedInvalid query parameters.
429RATE_LIMIT_EXCEEDED(same pattern)
500INTERNAL_SERVER_ERRORInternal Server ErrorCatch-all.

​
Global Errors (all endpoints)

These can be returned by any endpoint:
HTTPCodeMessageNotes
400MISSING_API_CREDENTIALSMissing API credentialsNo Authorization header or partner-id header provided.
400INVALID_API_CREDENTIALS_FORMATInvalid API credentials formatAuthorization header is malformed (expected id:secret).
401INVALID_API_CREDENTIALSInvalid API credentialsCredentials don’t match any active partner.
401AUTHENTICATION_FAILEDAuthentication failedAuth check threw an unexpected error.
401INVALID_SECURITY_SCHEMEInvalid security schemeRequest used an unsupported authentication method. Internal safeguard — should not occur in normal usage.
403ACCESS_DENIEDAccess restricted for partner-id requestsOperation not allowed for public partner-id access.
404ROUTE_NOT_FOUNDRoute not foundThe requested URL path doesn’t match any v2 endpoint.
429RATE_LIMIT_EXCEEDED(dynamic — see special shape above)Per-partner, per-operation rate limits.
503SERVICE_UNAVAILABLEService UnavailableBackend service is temporarily unavailable.
500INTERNAL_SERVER_ERRORInternal Server ErrorUnhandled exception.

​
HTTP Status Summary

StatusMeaningCode Strings
400Bad RequestMISSING_API_CREDENTIALS, INVALID_API_CREDENTIALS_FORMAT
401UnauthorizedINVALID_API_CREDENTIALS, AUTHENTICATION_FAILED, INVALID_SECURITY_SCHEME
403ForbiddenACCESS_DENIED
404Not FoundNOT_FOUND, ROUTE_NOT_FOUND
422Unprocessable EntityVALIDATION_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
429Too Many RequestsRATE_LIMIT_EXCEEDED
500Internal Server ErrorINTERNAL_SERVER_ERROR, UNABLE_TO_PERFORM_EXCHANGE
503Service UnavailableSERVICE_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: 
    /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?

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