Error Handling

All error responses follow a consistent format:

{
  "error": "Human-readable error message",
  "details": "Optional additional context"
}

HTTP Status Codes

Code	Meaning	When
200	Success	Request completed successfully
400	Bad Request	Invalid request body, missing fields, malformed data
401	Unauthorized	Missing or invalid X-API-Key header
404	Not Found	No pools for the pair, or quote ID not found
410	Gone	Quote expired (30s TTL)
429	Too Many Requests	Rate limit exceeded — check Retry-After header
500	Internal Server Error	Server-side failure (swap build failed, etc.)
502	Bad Gateway	Jito submission failed
503	Service Unavailable	Blockhash not available (server just started)

Rate Limit Errors

{
  "error": "Rate limit exceeded",
  "limit": 60,
  "windowMs": 60000,
  "retryAfterSeconds": 12
}

The Retry-After HTTP header is also set.

Validation Errors

{
  "error": "Invalid request",
  "details": "Invalid type: Expected string but received undefined (path: inputMint)"
}

Handling Tips

• Always check the HTTP status code first
• Parse the error field for user-facing messages
• Use details for debugging (not user-facing)
• On 429, respect Retry-After — don't retry immediately
• On 503, retry after 2-3 seconds (server is warming up)
• On 502, the transaction may or may not have been sent — check the signature on-chain before retrying