Error Codes

HTTP Status Codes

Code	Name	Description
200	OK	Request successful
400	Bad Request	Invalid parameters
402	Payment Required	No valid payment proof
404	Not Found	Symbol or endpoint not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server-side error
503	Service Unavailable	DEX data source temporarily down

Error Response Format

{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {}
}

Error Reference

payment_required (402)

No payment proof provided.

{
  "error": "payment_required",
  "message": "This endpoint requires payment via x402",
  "details": {
    "amount": "0.01",
    "token": "USDC",
    "network": "base",
    "recipient": "0x4SEC_RECEIVER_ADDRESS"
  }
}

Fix: Use the x402 client SDK for automatic payment.

invalid_payment (402)

Payment signature verification failed. Fix: Check wallet private key.

insufficient_payment (402)

Payment amount less than required.

{
  "error": "insufficient_payment",
  "details": { "required": "0.01", "provided": "0.005" }
}

symbol_not_found (404)

{
  "error": "symbol_not_found",
  "message": "Symbol XYZ not supported",
  "supported_symbols": ["BTC", "ETH", "SOL", "ARB", "OP", "MATIC", "AVAX", "DOT", "LINK", "UNI"]
}

rate_limit_exceeded (429)

{
  "error": "rate_limit_exceeded",
  "retry_after": 30
}

invalid_parameters (400)

{
  "error": "invalid_parameters",
  "details": {
    "field": "interval",
    "allowed": ["1m", "5m", "15m", "1h", "4h", "1d"]
  }
}

internal_error (500)

{
  "error": "internal_error",
  "message": "Unexpected error. Please try again.",
  "request_id": "req_abc123"
}

Fix: Retry. If persistent, contact support with request_id.