Docs topic · Error handling

How do I troubleshoot Pokerai API errors?

Use the operation's public HTTP response and schema first; solver progress statuses are separate from the shared error body.

Updated 2026-07-26

Direct answer: match the HTTP status and the endpoint's current Reference or OpenAPI snapshot. The shared public Error schema has error and may include message; solver status, spot_status, and node_status are separate response fields.

Quick facts

Fact	Public contract
Error body	The shared `Error` schema documents `error` and `message`. Do not assume either field has an unpublished shape or that every operation returns identical fields.
Authentication	`401` means a missing or invalid API key for operations that declare `Unauthorized`.
Validation	`400` is documented for invalid input or a missing field on applicable GTO operations. Check that operation's current request schema.
Quota and capacity	`429` is documented for monthly quota exhaustion on applicable operations; solver scheduling can also return `{ "status": "busy" }`.
Solver progress	`status`, `spot_status`, and `node_status` describe the asynchronous solver workflow, not the shared `Error` schema.

Minimal failed request and response

curl -s https://pokerai.bet/v1/gto/preflop \
  -H "Content-Type: application/json" \
  -d '{"hole_cards":"AhKh","positions":{"hero":"UTG"},"preflop_actions":[{"position":"SB","action":"small blind","amount":0.5},{"position":"BB","action":"big blind","amount":1}]}'

HTTP 401
{ "error": "missing_api_key" }

This minimal failure shape uses the public Error field example. Do not log API keys or request headers while diagnosing it.

Authentication, validation, and quota boundaries

HTTP	Public meaning	Next check
400	Invalid input or missing field.	Compare the JSON body with the operation's current Reference or OpenAPI request schema.
401	Missing or invalid API key.	Send one supported key header; see Authentication.
404	No GTO data for a spot or board on operations that declare `NoSolution`.	Check the submitted spot or board against that operation's documented coverage.
429	Monthly quota exceeded, or `status: busy` when all solver hosts are busy for solver scheduling.	For quota, see Quotas and the dashboard. For `busy`, treat it as capacity state and follow the current solver operation contract; this page makes no retry-timing guarantee.
502 / 503	`502` is a temporarily unavailable backend on applicable operations. `503` can report `upstream_unavailable` after the service's own retries.	The OpenAPI contract marks the `503` upstream case retryable; do not infer a retry count, delay, or SLA.

Solver status is not an error code

After POST /v1/gto/solver, scheduling can return status values computing, queryable, or busy. Poll POST /v1/gto/solver/tree until spot_status is queryable. The public tree contract also defines available, computing, expired, and no_nodes; no_nodes is terminal, so stop polling. Node responses separately define node_status values including error, with message present for that node state.

An expired node means the solve was reclaimed or replaced; the public contract says to reschedule. Do not translate solver statuses into a promise about completion time, capacity, or charges beyond the endpoint's current public documentation.

Safe use and escalation

Use Pokerai API for training, coaching, hand review, study, and research. Real-money real-time assistance (RTA) is prohibited. For an unresolved public-contract question, keep the endpoint, HTTP status, and redacted response body, then use the official Contact channel; never include an API key.