Error Codes

All API errors follow a consistent format for easy handling and debugging.

Error Response Format

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid chain ID: 999999",
    "details": {
      "field": "fromChain",
      "value": "999999"
    }
  }
}

Common Error Codes

Code	HTTP Status	Description
VALIDATION_ERROR	400	Invalid request parameters
UNSUPPORTED_CHAIN	400	Chain not supported
INSUFFICIENT_LIQUIDITY	404	No routes found with sufficient liquidity
TOKEN_NOT_FOUND	404	Token address not recognized
TRANSACTION_NOT_FOUND	404	Transaction hash not found
RATE_LIMIT_EXCEEDED	429	Too many requests
INTERNAL_ERROR	500	Server error
SERVICE_UNAVAILABLE	503	Service temporarily unavailable

Error Handling Best Practices

1. Always Check Response Status

async function getQuote(params) {
  try {
    const response = await fetch('https://xplore.api.v2.routerprotocol.com/v1/quote?' + new URLSearchParams(params));

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error?.message || 'Quote request failed');
    }

    return await response.json();
  } catch (error) {
    console.error('Quote error:', error);
    throw error;
  }
}

2. Handle Specific Error Codes

try {
  const quote = await getQuote(params);
} catch (error) {
  if (error.error?.code === 'INSUFFICIENT_LIQUIDITY') {
    // Show user-friendly message
    console.log('No routes available for this swap');
  } else if (error.error?.code === 'RATE_LIMIT_EXCEEDED') {
    // Implement retry logic
    console.log('Rate limit exceeded, please wait');
  } else {
    // Handle other errors
    console.error('Unexpected error:', error);
  }
}

3. Validate Input Before Request

function validateQuoteParams(params) {
  if (!params.fromChain || !params.toChain) {
    throw new Error('Chain IDs are required');
  }
  if (!params.fromToken || !params.toToken) {
    throw new Error('Token addresses are required');
  }
  if (!params.fromAmount || parseFloat(params.fromAmount) <= 0) {
    throw new Error('Valid amount is required');
  }
  return true;
}

HTTP Status Codes

Success Codes

Code	Description
200 OK	Request successful
201 Created	Resource created successfully

Client Error Codes

Code	Description
400 Bad Request	Invalid request parameters
401 Unauthorized	Missing or invalid API key
403 Forbidden	Access denied
404 Not Found	Resource not found
429 Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Description
500 Internal Server Error	Server error
502 Bad Gateway	Upstream service error
503 Service Unavailable	Service temporarily unavailable
504 Gateway Timeout	Request timeout