← All guides
On this page
  1. Home
  2. Guides
  3. How should I handle Pokerai API errors and retries?
Guide Start here · 02/06 Platform 7 min Intermediate

How should I handle Pokerai API errors and retries?

Read the HTTP status and the current operation contract first: correct documented 400 and 401 responses, distinguish quota exhaustion from solver capacity at 429, and retry only the applicable transient 5xx cases without assuming a retry count or SLA.

Updated Maintained by Pokerai API

Direct answer: Use the current Reference or OpenAPI snapshot for the operation you called. The shared public Error schema documents error and may include message; do not infer an unpublished error-code vocabulary or identical response fields for every operation.

Quick facts

Error shapeThe public shared Error schema has error and may include message.
400 / 401For applicable operations, 400 documents invalid input or a missing field; 401 documents a missing or invalid API key.
429Applicable operations document monthly quota exhaustion; solver scheduling can also return { "status": "busy" } when all solver hosts are busy.
5xxSome applicable operations document a temporarily unavailable backend (502) or retryable upstream_unavailable response (503).
QuotaPublic quota counters are monthly; the OpenAPI quota response says they reset on the 1st. Check the dashboard and quota docs for the current account state.
Use boundaryTraining, coaching, hand review, study, and research only; no real-money RTA.

Minimal request and redacted error response

This deliberately omits credentials. It demonstrates the public authentication boundary without exposing a key or request header.

curl -i -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}]}'

The OpenAPI Error example supports this redacted response shape for a missing key:

HTTP 401
{ "error": "missing_api_key" }

Never log API keys, Authorization headers, or unredacted customer request bodies while diagnosing an error.

Safe retry and backoff principles

Retry only after classifying the response against the current operation contract. For an applicable transient 502 or retryable 503, use a bounded exponential backoff with jitter that your application owns. For solver scheduling 429 with status: busy, treat it as capacity state and retry later rather than assuming it is quota exhaustion.

Do not promise or hard-code a number of attempts, delay, SLA, idempotency behavior, or an error-code meaning beyond the current public contract. Before re-submitting a request that could consume quota or change workflow state, decide in your own application whether repeating it is safe.

When not to retry

Do not retry an unchanged applicable 400: compare the payload with the current request schema and correct the invalid or missing input. Do not retry an applicable 401 until you have corrected the supported API-key header or key.

Do not treat every 429 as retryable. When the response is documented quota exhaustion, check the dashboard, plan, and monthly reset boundary instead. A response shape such as status: busy belongs to the documented solver scheduling workflow, not the shared error schema.

Quota and solver status

Pokerai API meters presolved lookups separately from real-time solves. The public quota response describes a monthly counter that resets on the 1st; use the dashboard and pricing for current account limits rather than hard-coding a limit in a client.

Solver status, spot_status, and node_status are workflow fields separate from the shared Error schema. Follow the documented solver, tree, and node contracts instead of translating those states into a completion-time or charge guarantee.

No real-money RTA

Use Pokerai API for training, coaching, hand review, study, and research only. Real-time assistance at real-money tables is prohibited. Error handling and retry logic must not be used to automate live-table advice.

Documented status guide

These descriptions apply only where the operation's current OpenAPI response list declares them.

HTTPPublic contractSafe next step
400Invalid input or missing field.Correct the request schema mismatch; do not retry it unchanged.
401Missing or invalid API key.Correct authentication; do not retry with the same missing or invalid credential.
429Monthly quota exhaustion on applicable operations; solver scheduling can instead report status: busy.For quota, inspect the dashboard and reset boundary. For documented busy, use cautious backoff without a fixed retry promise.
502 / 503Applicable operations document a temporarily unavailable backend or retryable upstream_unavailable.Use application-owned bounded exponential backoff with jitter; re-check the current operation contract.

SDK, docs, and reference