错误响应

#HTTP 状态码

码	含义
`200`	成功
`400`	查询校验失败，或请求内容前后不一致
`404`	资源不存在
`429`	超出速率限制
`500`	服务器错误

#响应 envelope

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": [
    "outcomeId must be a string",
    "outcomeId should not be empty"
  ]
}

字段	说明
`statusCode`	与 HTTP 状态相同的数字
`error`	简短的人类可读标签（`"Bad Request"`、`"Not Found"`）。`429` 和 `500` 时不存在。
`message`	string 或 string[]。查询校验失败为数组；由处理函数直接抛出的错误（盘口缺少 `outcomeId`、市场不存在）为单个字符串。

注意 message 可能是数组

请求校验器的校验失败以 message: string[] 返回。不要简单地把 error.message 当作单行显示，而应分别渲染数组的每个元素。

#客户端处理模式

type ApiError = {
  statusCode: number;
  error?: string;
  message: string | string[];
};
 
async function call() {
  const res = await fetch(url, init);
  if (!res.ok) {
    const err = (await res.json()) as ApiError;
    const messages = Array.isArray(err.message) ? err.message : [err.message];
    throw new Error(messages.join('\n'));
  }
  return res.json();
}

#常见场景

情形	响应
盘口缺少 `outcomeId`	400 + `"outcomeId is required"`
时序价格缺少 `outcomeId`	400 + `["outcomeId must be a string", "outcomeId should not be empty"]`
错误的 enum 值	400 + `["status must be one of the following values: ACTIVE, RESOLVED, CANCELLED"]`
未定义的查询参数	400 + `["property foo should not exist"]`
市场不存在	404 + `"Market not found: <id or slug>"`
结果不存在	404 + `"Outcome not found"`
结果属于其他市场	400 + `"Outcome does not belong to this market"`
Rate limit	429 + `"ThrottlerException: Too Many Requests"` （无 `error` 字段）

#Rate limit

公开接口按 IP 进行限流 —— 具体数值参见速率限制。

收到 429 时请在短暂退避（数秒）后重试。若持续被拦截，请参考 Retry-After 头。

#下一步

分页 —— 正常响应的 list envelope
REST → Markets —— 实际端点

本页面是否有帮助？