Errors
API Errors
When a Sports or Casino request fails, the answer is a small JSON object with error and message. Your code should check error: it is a fixed code that never changes. message is a short fixed sentence for people to read.
Error format
JSON
{
"error": "event_not_found",
"message": "Event not found"
}| Field | Meaning |
|---|---|
error | The error code. Use this in your code. |
message | A short sentence about the error. It is always the same for a code. |
GET /api/v1/health answers differently: { "status": "ok", ... } with HTTP 200 when the API is working, or { "status": "degraded", ... } with HTTP 503 when part of it is not answering.
A 429 answer also has a Retry-After header: the number of seconds to wait. The body is { "error": "rate_limited", "message": "Too many requests" }.
Status codes
| HTTP | error | Message | When |
|---|---|---|---|
| 400 | invalid_sport | Unsupported sport. Supported sports: cricket, football, tennis, horse-racing, greyhound-racing | The sport in the address is not one of the supported sport keys. |
| 400 | invalid_event_id | Event id must be a positive integer | The event id is not a whole number above zero, or is longer than 20 digits. |
| 400 | invalid_query | Query parameters are not valid | A games filter is empty or too long, or the query could not be read. |
| 400 | invalid_page | Page must be a positive integer | page is not a whole number of 1 or more. Leave it out to get page 1. |
| 400 | invalid_limit | Limit must be between 1 and 100 | limit is not a whole number from 1 to 100. |
| 400 | unsupported_currency | Currency is not enabled for this API client | The currency is not allowed for your account, or it is not the player's currency. A player keeps the currency of their first launch. |
| 400 | invalid_provider | Provider filter is not valid | provider is not a provider id from GET /api/v1/casino/providers. Ids are case-sensitive. |
| 400 | invalid_category | Category filter is not valid | category is not a category id from the games list. Ids are case-sensitive. |
| 400 | invalid_launch | Launch request is not valid | The launch request has a missing or wrong field, an unknown field, or is not valid JSON. |
| 400 | invalid_wallet | Wallet request is not valid | The wallet request has a missing or wrong field, an unknown operation, a badly written amount or currency, or a rollback amount that differs from the original. |
| 400 | player_not_configured | Player country or currency is not configured | Your account's casino settings (country, currency or language) are not complete, so a new player cannot be created. Contact HZURA. |
| 403 | ip_not_allowed | Client address is not allowed | Access was refused. The API key is missing, empty, unknown or switched off, or your server's IP address is not on your allow-list. For safety, the answer does not say which. |
| 403 | sport_not_allowed | This sport is not enabled for this API client | The sport exists, but it is not enabled for your account. |
| 403 | casino_access_disabled | Casino access is not enabled | Casino is switched off for your account. On the transfer wallet only CREDIT is refused, so players can still be paid out. |
| 403 | game_not_available | Game is not available | The game exists but cannot be opened with this currency, language, device or mode. Demo needs a game with demo_support: true. |
| 404 | not_found | Route not found | The address does not exist. If your access check fails first, you get ip_not_allowed instead. |
| 404 | event_not_found | Event not found | No event with this id exists for this sport. |
| 404 | odds_not_found | Odds are not available for this event | The event exists, but it has no odds yet. |
| 404 | game_not_found | Game not found | No game with this id exists. |
| 404 | player_not_found | Player not found | This player_id has never been launched. A player is created by their first launch, not by the wallet. |
| 404 | wallet_transaction_not_found | Wallet transaction not found | The rollback points to a transaction_id this player does not have. |
| 405 | method_not_allowed | Method not allowed | The address exists, but not with this HTTP method (for example GET instead of POST). |
| 409 | insufficient_balance | Wallet balance is not sufficient | The player's casino balance is too low for this withdrawal or rollback. Nothing moved. |
| 409 | wallet_idempotency_conflict | Wallet transaction does not match the original request | This transaction_id was already used for a different request (another player, operation, amount, currency or rollback reference). |
| 409 | wallet_transaction_pending | Wallet transaction is still in progress | Only when you repeat a transfer made with the previous version of the wallet. New transfers never return it. Contact HZURA. |
| 409 | wallet_already_rolled_back | Wallet transaction is already rolled back | The transfer you want to reverse has already been reversed. |
| 409 | wallet_transaction_not_reversible | Wallet transaction cannot be rolled back | The transfer you want to reverse was refused, or is itself a rollback. |
| 409 | wallet_mode_mismatch | This customer uses the seamless wallet | Your account uses the seamless wallet, so HZURA holds no balance and this route is not used. |
| 413 | payload_too_large | Request payload too large | The request body is larger than 8 KiB. |
| 429 | rate_limited | Too many requests | Too many sports requests in a short time. Wait the number of seconds in the Retry-After header. |
| 500 | internal_error | Internal server error | Something went wrong on our side. Try again later. |
| 502 | malformed_upstream_data | Upstream data could not be read | The event or odds data could not be read. Try again shortly. |
| 502 | launch_authentication_failed | Game launch could not be authenticated | The game could not be opened right now. Try again shortly. |
| 502 | launch_failed | Game launch failed | The game provider refused to open the game or sent no game link. |
| 502 | wallet_provider_failed | Wallet transaction failed | Only when you repeat a transfer that the previous version of the wallet refused. New transfers never return it. |
| 503 | security_config_unavailable | Service is temporarily unavailable | Your access could not be checked right now, so the request was refused. Try again shortly. |
| 503 | catalog_unavailable | Event data is not available yet, retry shortly | Events for this sport are not available yet. Try again shortly. |
| 503 | redis_unavailable | Upstream data store is unavailable | The service is temporarily unavailable. Try again shortly. |
| 503 | casino_catalog_unavailable | Casino catalog is not available yet, retry shortly | The game list is temporarily unavailable. Try again shortly. |
| 503 | launch_not_configured | Game launch is not available | Game launch is temporarily unavailable. Try again later or contact HZURA. |
| 503 | player_store_unavailable | Player identity is not available | Players could not be looked up right now. Try again shortly. |
| 503 | wallet_not_configured | Casino wallet is not available | The wallet is not ready for your account. On the seamless wallet this means your wallet URL or signing secret is not set up yet, so real-money launches are refused. Contact HZURA. |
| 503 | wallet_store_unavailable | Casino wallet is not available | The wallet is temporarily unavailable. Repeat the same request; money never moves twice. |
| 504 | redis_timeout | Upstream data store timed out | The service took too long to answer. Try again shortly. |
| 504 | launch_unavailable | Game launch is temporarily unavailable | The game provider did not answer in time. Launch never moves money, so it is safe to try again. |
Access refused
Every access failure returns the same code. A wrong key and an unknown IP address look the same, so nobody can use the answer to guess which part failed.
| HTTP | error | Where |
|---|---|---|
| 403 | ip_not_allowed | Sports and Casino |
Request problems
Something in the address, the filters or the JSON body is wrong. Fix it before sending again.
| HTTP | error | Where |
|---|---|---|
| 400 | invalid_sport | Sports |
| 400 | invalid_event_id | Sports |
| 400 | invalid_query | Casino |
| 400 | invalid_page | Casino |
| 400 | invalid_limit | Casino |
| 400 | unsupported_currency | Casino |
| 400 | invalid_provider | Casino |
| 400 | invalid_category | Casino |
| 400 | invalid_launch | Casino |
| 400 | invalid_wallet | Wallet |
| 400 | player_not_configured | Casino |
| 405 | method_not_allowed | All routes |
| 413 | payload_too_large | Casino launch and wallet |
Not found
The address, event, game, player or transfer does not exist for your account.
| HTTP | error | Where |
|---|---|---|
| 404 | not_found | All routes |
| 404 | event_not_found | Sports |
| 404 | odds_not_found | Sports |
| 404 | game_not_found | Casino |
| 404 | player_not_found | Wallet |
| 404 | wallet_transaction_not_found | Wallet |
Wallet refusals
The wallet refused the operation and nothing moved. Repeating the same transaction_id returns the same answer and never moves money twice.
| HTTP | error | Where |
|---|---|---|
| 409 | insufficient_balance | Wallet |
| 409 | wallet_idempotency_conflict | Wallet |
| 409 | wallet_transaction_pending | Wallet |
| 409 | wallet_already_rolled_back | Wallet |
| 409 | wallet_transaction_not_reversible | Wallet |
| 409 | wallet_mode_mismatch | Wallet |
Rate limits
Sports requests have a limit per time window. Wait for Retry-After. Casino requests do not have this limit.
| HTTP | error | Where |
|---|---|---|
| 429 | rate_limited | Sports |
Data or game problems
The data could not be read, or the game could not be opened. Try again shortly.
| HTTP | error | Where |
|---|---|---|
| 500 | internal_error | All routes |
| 502 | malformed_upstream_data | Sports |
| 502 | launch_authentication_failed | Casino |
| 502 | launch_failed | Casino |
| 502 | wallet_provider_failed | Wallet |
Temporarily unavailable
Try again shortly with the same request. Wallet requests are safe to repeat with the same transaction_id.
| HTTP | error | Where |
|---|---|---|
| 503 | security_config_unavailable | Sports and Casino |
| 503 | catalog_unavailable | Sports |
| 503 | redis_unavailable | Sports and Casino |
| 503 | casino_catalog_unavailable | Casino |
| 503 | launch_not_configured | Casino |
| 503 | player_store_unavailable | Casino |
| 503 | wallet_not_configured | Casino launch and wallet |
| 503 | wallet_store_unavailable | Casino launch and wallet |
| 504 | redis_timeout | Sports |
| 504 | launch_unavailable | Casino |
What to do
| Answer | What to do |
|---|---|
| 400 | Fix the request. Sending it again unchanged gives the same error. |
403 ip_not_allowed | Check your API key and your server's public IP address with HZURA. |
429 rate_limited | Wait Retry-After seconds, then try again. Sports only. |
409 insufficient_balance | The balance is too low. Try again only when it is enough, with a new transaction_id. |
409 wallet_idempotency_conflict | This transaction_id was used for a different request. Use a new one. |
409 wallet_mode_mismatch | Your account uses the seamless wallet. Your own wallet answers HZURA's requests instead. |
409 wallet_transaction_pending or 502 wallet_provider_failed | Only seen when repeating a transfer from the previous wallet version. Contact HZURA, and use a new transaction_id for a new attempt. |
503 wallet_store_unavailable | Send the same request again with the same transaction_id. Money never moves twice. |
504 launch_unavailable | Send the same launch again. Launching never moves money. |
| Other 502, 503 and 504 errors | Temporary. Wait a little and send the same request again. |