Error Response Format

All errors follow a standard JSON structure:

{
  "statusCode": 400,
  "message": "Detailed error description",
  "error": "Bad Request"
}

Field	Type	Description
`statusCode`	number	HTTP status code
`message`	string	Human-readable error description
`error`	string	Error type classification

HTTP Status Codes

Code	Error	Description
`400`	Bad Request	Invalid request parameters or body
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Valid API key but insufficient permissions
`404`	Not Found	Resource not found (order, quote, wallet)
`409`	Conflict	Resource conflict (e.g., duplicate wallet address)
`422`	Unprocessable Entity	Request understood but cannot be processed
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server error
`503`	Service Unavailable	Service temporarily unavailable

Common Error Messages

Authentication Errors (401)

Message	Cause	Solution
`Invalid or missing API key`	No Authorization header or invalid key	Include valid `Authorization: Bearer <key>` header
`API key expired`	Key has been revoked or expired	Generate a new API key in the dashboard

Validation Errors (400)

Message	Cause	Solution
`symbol is required`	Missing trading pair	Include `symbol` field (e.g., `USDT/BRL`)
`Invalid symbol`	Unsupported trading pair	Use a supported symbol: `USDT/BRL`, `USDC/BRL`, `BTC/BRL`, `ETH/BRL`
`type must be on_ramp or off_ramp`	Invalid quote type	Use `on_ramp` or `off_ramp`
`amount must be at least 10`	Amount below minimum	Increase amount to R$ 10 or more
`Invalid network for asset`	Asset/network mismatch	Check supported network for the asset
`Invalid wallet address`	Malformed address	Verify the address format for the network

Quote Errors (400/404)

Message	Cause	Solution
`Quote not found`	Invalid quote ID	Verify the quote ID
`Quote expired`	Quote validity period ended	Create a new quote
`Quote already used`	Quote already converted to order	Create a new quote

Order Errors (400/404/422)

Message	Cause	Solution
`Order not found`	Invalid order ID	Verify the order ID
`destination.asset is required`	Missing asset in order	Include destination asset
`destination.network is required`	Missing network	Include destination network
`Insufficient liquidity`	Cannot fulfill order at this time	Try again later or reduce amount
`Order cannot be canceled`	Order already processing	Only `PENDING_DEPOSIT` orders can be canceled

Wallet Address Errors (400/404/409)

Message	Cause	Solution
`Wallet address not found`	Invalid wallet ID	Verify the wallet address ID
`Address already registered`	Duplicate address	Use the existing wallet or delete it first
`Cannot delete default address`	Trying to delete default	Set another address as default first

Rate Limit Errors (429)

Message	Cause	Solution
`Rate limit exceeded`	Too many requests	Wait before retrying; implement backoff

Error Handling Best Practices

Always check status codes: Don't assume success; validate the response
Log error responses: Store the full error response for debugging
Implement retry logic: For 5xx errors and 429, retry with exponential backoff
Show user-friendly messages: Translate API errors to meaningful messages for end users
Handle specific errors: Different errors require different handling strategies

Example: Error Handling

async function createOrder(orderData) {
  try {
    const response = await fetch('/v1/orders', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(orderData)
    });
    
    if (!response.ok) {
      const error = await response.json();
      
      switch (response.status) {
        case 400:
          throw new Error(`Validation error: ${error.message}`);
        case 401:
          throw new Error('Authentication failed. Check your API key.');
        case 422:
          throw new Error(`Cannot process: ${error.message}`);
        case 429:
          throw new Error('Rate limit exceeded. Please wait.');
        default:
          throw new Error(`API error: ${error.message}`);
      }
    }
    
    return await response.json();
  } catch (err) {
    console.error('Order creation failed:', err);
    throw err;
  }
}