Docs topic · 错误处理

如何排查 Pokerai API 错误？

先以操作的公开 HTTP 响应和 schema 为准；solver 进度状态与共享错误体是不同概念。

更新于 2026-07-26

直接答案：请匹配 HTTP 状态和该端点当前的 Reference或OpenAPI snapshot。共享公开 Error schema 包含 error，并且可能包含 message；solver 的 status、spot_status 与 node_status 是独立响应字段。

Quick facts

事项	公开 contract
错误体	共享 `Error` schema 公开了 `error` 和 `message`。不要假设字段具有未公开形状，也不要假设每个操作返回完全相同的字段。
鉴权	声明 `Unauthorized` 的操作中，`401` 表示 API Key 缺失或无效。
校验	适用的 GTO 操作中，`400` 表示输入无效或缺少字段。请查看该操作当前 request schema。
配额与容量	适用操作中 `429` 表示月度配额耗尽；solver 调度也可能返回 `{ "status": "busy" }`。
Solver 进度	`status`、`spot_status` 和 `node_status` 描述异步 solver 工作流，不属于共享 `Error` schema。

最小失败请求与响应

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" }

这个最小失败形状采用公开 Error 字段示例。排查时不要记录 API Key 或请求头。

鉴权、校验与配额边界

HTTP	公开含义	下一步
400	输入无效或缺少字段。	将 JSON body 与该操作当前 Reference 或 OpenAPI request schema 对照。
401	API Key 缺失或无效。	发送一种支持的 Key header；参见鉴权。
404	声明 `NoSolution` 的操作中，提交的 spot 或 board 没有 GTO 数据。	按该操作公开覆盖范围检查提交的 spot 或 board。
429	月度配额耗尽，或 solver 调度时全部 solver host 繁忙的 `status: busy`。	配额请查看配额与控制台。对于 `busy`，将其视为容量状态并遵循当前 solver operation contract；本页不承诺重试时机。
502 / 503	适用操作中的 `502` 表示 backend 暂时不可用。服务自行重试后仍无法连接 solver 时，`503` 可返回 `upstream_unavailable`。	OpenAPI contract 将 `503` 上游情况标为可重试；不要推断重试次数、间隔或 SLA。

Solver 状态不是错误码

POST /v1/gto/solver 后，调度可返回 status：computing、queryable 或 busy。轮询 POST /v1/gto/solver/tree，直到 spot_status 是 queryable。公开 tree contract 还定义了 available、computing、expired 与 no_nodes；no_nodes 为终态，应停止轮询。节点响应另行定义 node_status，其中包含 error，且该节点状态有 message。

expired node 表示 solve 已被回收或替换；公开 contract 指示重新调度。不要把 solver 状态解读为完成时间、容量或费用保证，除非端点当前公开文档已有明确说明。

安全使用与升级处理

Pokerai API 用于训练、教学、手牌复盘、学习和研究。禁止在真实资金牌桌上提供实时辅助（RTA）。若公开 contract 问题仍无法解决，请保留端点、HTTP 状态和已脱敏的响应体，并通过官方联系渠道咨询；绝不要包含 API Key。