Swap API Error Handling

​

HTTP Status Codes

​

2xx: Success

• 200 OK: The request was successful, and the server returned the expected response.

​

4xx: Client Errors

• 400 Bad Request: The request is malformed or contains invalid parameters.
• 401 Unauthorized: The Bearer API key is missing or invalid (returned once API-key enforcement is enabled).
• 403 Forbidden: The client does not have permission to access the requested resource.
• 404 Not Found: The requested resource could not be found.
• 429 Too Many Requests: The client has exceeded the allowed rate limit.

​

5xx: Server Errors

• 500 Internal Server Error: An unexpected error occurred on the server.
• 502 Bad Gateway: The server received an invalid response from an upstream server.
• 503 Service Unavailable: The service is temporarily unavailable, possibly due to maintenance or overload.

​

Error Response Format

​

Application errors

{
  "error_code": "PAIR_NOT_FOUND",
  "message": "Trading pair not found: BTC/USDT",
  "details": {},
  "request_id": "req_01HV8Q9X7G0Q7Y3Z"
}

• error_code (string): Stable, machine-readable error code (e.g. PAIR_NOT_FOUND, VALIDATION_ERROR, NOT_FOUND, RATE_LIMIT_EXCEEDED, INTERNAL_ERROR).
• message (string): Human-readable description of the error.
• details (object): Optional structured context about the error (may be empty).
• request_id (string): Request correlation identifier — include it when contacting support.

​

Request-validation errors (HTTP 422)

{
  "detail": [
    {
      "loc": ["body", "rfq_id"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

• detail (array<object>): One entry per validation failure.
  • loc (array<(string | integer)>): Path to the offending field.
  • msg (string): Validation error message.
  • type (string): FastAPI/Pydantic validation error type.

​

Legacy errors

{
  "detail": "Route not supported for this pair. From: BTC_LN, To: RGB_LN"
}

• detail (string): Human-readable description of the error.

​

Common Errors

​

400 Bad Request

• Cause: Missing or invalid parameters in the request.
• Solution: Verify the request payload and ensure all required fields are provided with valid data.

​

404 Not Found

• Cause: The requested endpoint or resource does not exist.
• Solution: Check the endpoint URL and resource identifiers.

​

429 Too Many Requests

• Cause: The client has sent too many requests in a short period.
• Solution: Implement rate-limiting in your client application and retry after the specified wait time (if provided).

​

500 Internal Server Error

• Cause: An unexpected error occurred on the server.
• Solution: Retry the request later. If the issue persists, contact support with details about the request.

​

WebSocket Error Handling

​

Reconnection Strategy

1. Wait for a few seconds (e.g., 5-10 seconds).
2. Re-establish the connection.
3. Re-issue any pending quote_request messages to obtain fresh quotes.

​

Debugging Tips

1. Check Logs: Monitor your application logs for details about failed requests.
2. Validate Inputs: Ensure all request parameters and payloads meet the API requirements.
3. Contact Support: For persistent or unclear errors, provide the following details:
   • Request URL
   • HTTP method
   • Request payload
   • Timestamp of the error
   • Full error response from the API

​

Best Practices

1. Handle Errors Gracefully: Implement proper error-handling logic in your application to avoid crashes or user frustration.
2. Rate-Limiting: Respect the API rate limits to avoid 429 Too Many Requests errors.
3. Retry Mechanism: For transient errors (e.g., 500 Internal Server Error), implement a retry mechanism with exponential backoff.