Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. All error responses follow a consistent JSON format.

Error Response Format

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

Field	Type	Description
message	string	A human-readable description of the error
error	string	A machine-readable error code

Error Codes

401 — Unauthorized

The client secret is missing, invalid, or belongs to an inactive client.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Invalid or inactive client secret",
  "error": "unauthorized"
}

Common causes:

• The X-Client-Secret header is missing from the request.
• The UUID is malformed or does not match any client.
• The client account has been deactivated.

Resolution: Verify that your client secret is correct and active. See Authentication.

---

404 — Not Found

The requested resource or endpoint does not exist.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "message": "Resource not found",
  "error": "not_found"
}

Common causes:

• Incorrect URL path (e.g., typo in the endpoint).
• Accessing a resource that does not exist.

Resolution: Verify the endpoint URL against the API Reference.

---

422 — Validation Error

One or more query parameters are invalid.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "error": "validation_error"
}

Common causes:

• Invalid date format (expected YYYY-MM-DD).
• Invalid transaction_type value (must be DEBIT, CREDIT, ROLLBACK, or FREE_SPIN).
• Non-numeric value for page or per_page.
• Invalid currency ISO code.

Resolution: Review the query parameters section of the corresponding endpoint documentation.

---

429 — Too Many Requests

You have exceeded the limit of 60 requests per minute.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "message": "Too many requests. Please try again later.",
  "error": "too_many_requests"
}

Resolution: Implement rate limiting in your integration. Wait at least 60 seconds before retrying. Consider caching responses for data that does not change frequently.

Rate Limiting Strategy

• Cache responses when data does not need to be real-time.
• Use date filters to reduce response sizes and minimize the number of requests.
• Implement exponential backoff when retrying after a 429 response.

---

500 — Server Error

An unexpected error occurred on the server.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "message": "An unexpected error occurred. Please try again later.",
  "error": "server_error"
}

Resolution: This is a server-side issue. If the error persists, contact support with your request details (endpoint, parameters, timestamp).

Best Practices

1. Always check the HTTP status code before processing the response body.
2. Handle errors gracefully — display meaningful messages to your users.
3. Implement retry logic with exponential backoff for 429 and 500 errors.
4. Log error responses (excluding the client secret) for debugging.
5. Do not retry 401 errors — they require corrective action (fixing the secret), not retrying.
6. Do not retry 422 errors — they indicate a problem with your request parameters.