NLHE Troubleshoot and Error Handling

This document describes the most frequent validation issues, all supported error codes, and the most common scenarios that lead to request failures when using the No Limit Texas Holdem game API.

This document is divided into three parts:

• Summary List for Checking Requests
• Complete NLHE Game Error Codes Table
• Common NLHE Game Validation Scenarios

---

Summary List for Checking Requests

Before sending a request, always verify the following:

• The API only supports Small Blinds equal to half of the Big Blind. (2:1 ratio)
• The API only supports 2 to 9 players games.
• Player chips in the request represent the chips that players have at the start of the hand, before any ante or blinds are paid. The API performs all chip calculations based on the provided actions.
• All amounts in the request must be expressed in chips, not in currency, big blinds, or pot percentages. Only a few specific fields accept pot percentages, and those are explicitly documented in the API documentation on the No Limit Texas Holdem Game API Reference page.
• Game state is mandatory. The API will not process games that have already finished or games that are waiting for a board card. The API always returns strategy for the next valid action.
• Game action order is mandatory. All actions and streets must follow the correct order: flop, turn, and river.
• Raises must be greater than or equal to the minimum legal bet amount. The minimum raise is always the size of the previous bet or raise. Pay attention specially to the first raise preflop, by the rule it needs to be twice the size of the highest blind (for 2 blinds twice the big blind, for 3 blinds twice the straddle).
• Player seats must be matched correctly. Always verify the blind position order: Dealer, Small Blind, Big Blind, and Straddle if applicable.
• Only the Hero cards must be present. It is mandatory that the current player, also known as the Hero, has their hole cards specified. The Hero is the player who will perform the next action based on the returned strategy.

---

NLHE Game Error Codes

This section lists all error codes that can occur when processing cash game No Limit Texas Holdem requests.

Complete NLHE Game Error Codes Table

Notes

• All known game validation errors return HTTP status 422 (Unprocessable Entity) with the responses described in the table above.
• Only E500 returns HTTP status 500 (Internal Server Error).
• During the current infrastructure migration, the API may temporarily return HTTP 502 (Bad Gateway) until the migration is completed at the end of 2025.

---

Common NLHE Game Validation Scenarios

This section groups the most frequent validation errors by category and explains how they typically occur.

Missing Required Fields (E111)

The following fields are mandatory in every request:

• request_id
• hand
• hand.gameuuid
• hand.game_mode_code
• hand.players
• hand.actions
• hand.actions.entries
• hand.big_blind
• hand.ante
• hand.dealer_seat
• hand.sb_seat
• hand.bb_seat
• hand.straddle_seat

All of these fields are described in the No limit texas hold'em Game API Reference page. If any of these fields are missing, the request will fail with error E111.

---

Invalid Actions (E105)

This error is returned when an action is syntactically valid but illegal for the current game state. Common causes include:

• Bet, raise, or allin actions missing the amount field
• Actions performed by players with no effective stack (stack minus ante and blinds less than or equal to zero)
• Actions that do not match the current game flow or betting round

---

Hero Validation (E102, E104, E106, E113)

The Hero is the player for whom the API returns the strategy. The following rules always apply:

• Exactly one Hero must exist in the hand
• The Hero must be the current player to act
• The Hero must have exactly two valid hole cards

Violations of these rules result in the following errors:

• E102 if no Hero is found\
• E113 if multiple Heroes are found\
• E104 if the Hero is not the current player\
• E106 if the Hero card string is invalid

---

Game State Validation (E101)

• The API does not accept terminal games.
• If the game has already finished, the API returns E101.

---

Action Format Validation (E103, E105)

Valid actions must be one of the following:

• fold
• call
• check
• bet
• raise
• allin
• Card strings such as 6sTd9c for flop and 4s for turn and river.

Additional rules:

• Bet, raise, and allin actions must always include an amount.
• All actions must be legal for the current street and betting round.