错误与限制

出错时会发生什么。

错误以 JSON 信封返回，包含稳定的 type、面向人的消息，以及报告问题时可提供给我们的 request_id。

真实响应 - 无效密钥（HTTP 401）

{"type": "error", "error": {
   "type": "authentication_error",
   "message": "Invalid or revoked API key.",
   "request_id": "063f8b83-eee2-4383-a5cf-11e4bcd29d7c"
 }}

HTTP	含义	处理方式
400	请求体格式错误（字段缺失或类型错误）	错误消息会指明具体字段 - 修正后重试。
401	API 密钥无效或已吊销	检查密钥；在控制台签发新密钥。
402	余额不足、未绑定银行卡，或触及等级上限	在控制台充值或绑定银行卡。响应中带有 `balance_cents` 和 `floor_cents`，可据此判断是哪一项拦住了您。
404	不存在该记忆、存储库或图像	检查 id。`get_image` 在记忆存在但不带图像时同样返回 404。
409	该名称已被占用	存储库和工作区的名称在账户内唯一 - 请另选一个。
413	请求体超过 10MB	Base64 比它编码的文件大约大 33%，所以请先把图像缩小再编码。
429	触发速率限制	SDK 已经替您重试过了，带退避与抖动，并遵守 `Retry-After`。收到它说明重试已经用尽 - 请降低并发，而不是自己再套一层循环。
501	该模型的引擎未实现此端点	图像和修订历史需要更新的引擎。`GET /api/v1/models` 会列出各个模型分别支持什么。
5xx	服务端问题	退避后重试，但不要盲目重试。此 API 的每一次调用都是 POST，服务端可能已经存下了您的请求，因此 SDK 不会自动重试 5xx。重发时请带上幂等键，让重复请求无法写入两次；联系我们时请附上 `request_id`。

每个错误都是 WosError，同时每个状态还各有自己的类 - BadRequestError、AuthenticationError、PaymentRequiredError、NotFoundError、ConflictError、RateLimitError、ServerError、APIConnectionError。请捕获您真正要处理的那一个，而不是去比较数字。

# SDK error handling (Python)
from wontopos import Client, WosError, RateLimitError, PaymentRequiredError

try:
    mem.search("...", user_id="alice")
except PaymentRequiredError: ...      # 402 - top up
except RateLimitError: ...            # 429 - the SDK already retried; slow down
except WosError as e: ...            # e.status, e.message, e.request_id
except (ValueError, TypeError): ...    # never left the client

有些错误根本到不了我们这里。API 密钥、存储库 id、幂等键和图片都在请求发出之前完成校验，此时抛出的是 ValueError 或 TypeError，而不是 WosError。单靠 except WosError 抓不到它们。

密钥安全。密钥仅在创建时显示一次，我们侧只保存其哈希。请保存在环境变量中；如有泄露，在控制台吊销 - 吊销立即生效。

速率限制按账户计，由您的所有密钥共享，并随等级提升 - 见用量等级。账户用量可在控制台查看。

Product

Models

Start

出错时会发生什么。