Error Handling

Understanding API error responses and codes

Error Handling

All errors return JSON with consistent structure and appropriate HTTP status codes.

Error Response Format

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for transaction",
    "details": {
      "required": "1.5 SOL",
      "available": "1.2 SOL"
    }
  }
}

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
404	Not Found - Resource doesn’t exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Common Error Codes

Quote Errors

Code	Description
INVALID_ASSET	Unsupported asset symbol
AMOUNT_TOO_SMALL	Below minimum amount
INSUFFICIENT_LIQUIDITY	Not enough liquidity

Transaction Errors

Code	Description
INVALID_QUOTE	Quote expired or not found
INVALID_SIGNATURE	Malformed signed transaction
INSUFFICIENT_BALANCE	Not enough tokens
ROUTING_UNAVAILABLE	Private mode unavailable

Authentication Errors

Code	Description
INVALID_API_KEY	API key is invalid
EXPIRED_API_KEY	API key has expired
RATE_LIMIT_EXCEEDED	Too many requests

Retry Logic

Implement exponential backoff for retries:

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }
}