Error Handling

A proper application must gracefully handle errors returned by the API. The xRocket Exchange API uses standard HTTP status codes to indicate the success or failure of a request.

When an error occurs, the API will return an appropriate HTTP status code and a JSON response body containing specific details about the error.

HTTP Status Codes

The API uses the following range of status codes:

Code	Meaning	Description
`200`	OK	The request was successful.
`400`	Bad Request	The request was invalid or contained errors (e.g., missing parameter, invalid symbol). Refer to the API Reference for a list of valid trading symbols.
`401`	Unauthorized	Authentication failed or missing (invalid Bearer Token). Check that your token is correctly set in the `Authorization: Bearer <token>` header.
`403`	Forbidden	The authenticated user does not have permission to access this resource.
`404`	Not Found	The requested endpoint or resource does not exist.
`429`	Too Many Requests	You have exceeded the API's rate limits. Implement a delay or "back-off" strategy in your code to slow down requests.
`500`	Internal Server Error	A generic server error occurred on our end.
`503`	Service Unavailable	The server is temporarily down for maintenance or overloaded.

Error Response Structure

When an error occurs, the API will typically return a JSON object with a consistent structure to help you debug the issue:

{
  "type": "/api/problems/client_data_validation",
  "title": "Client data validation error",
  "status": 400,
  "detail": "A human-readable description of the error.",
  "instance": "/api/problems/instances/ada06f0c-8ca8-457a-9906-4feb8c999169",
  "kind": "validation"
}

Rate Limits

To ensure fair usage and system stability, we enforce rate limits on our API endpoints.

warning

If you exceed the rate limits, you will receive a 429 Too Many Requests HTTP status code. The response headers will provide details on when you can retry your request (e.g., Retry-After header). Your application should catch this error and pause requests until the specified time has passed.

Troubleshooting Tips

Verify Authentication: Most issues stem from authentication errors. Double-check your Authorization: Bearer <TOKEN> header format.
Check Content-Type: Ensure Content-Type: application/json is set for all POST requests.
Use the Testnet: Always test new logic on the Testnet environment before deploying to the Mainnet.