错误

信封

每个失败的调用都返回结构相同的 JSON 响应体，以及对应的 HTTP 状态码。

{
  "error": {
    "code": "model_busy",
    "message": "model sam3 is busy; retry shortly",
    "retryable": true,
    "retryAfterMs": 5000
  }
}

字段	含义
code	稳定的、机器可读的错误码。应依据 code 而不是 message 判断。
message	面向人的说明，措辞可能变化。
retryable	为 true 时，原样重复请求有可能成功。
retryAfterMs	建议等待的毫秒数。无建议时为 0。

429 和 503 响应还带有 Retry-After 响应头，单位为整秒。

失败的调用不收费。返回错误的调用不会产生任何扣费。

错误码

状态码	错误码	可重试	含义
400	invalid_request	否	请求格式错误、字段超出范围，或图片未通过上传检查。
400	invalid_image	否	图片通过了上传检查，但无法解码。同一句柄之后始终返回该错误码。
400	unsupported	否	请求有效，但使用了尚未提供的功能，例如 image.url。
401	unauthorized	否	API 密钥缺失、格式错误、无效、已过期或已吊销。
402	insufficient_balance	否	余额不足以支付本次调用的价格。
403	model_locked	否	密钥的范围或账户所在的模型池不允许使用该模型。
403	email_unverified	否	密钥所有者尚未验证邮箱。
404	not_found	否	路径不存在。
404	image_not_found	否	img_ 句柄未知、已过期或已被淘汰。应重新上传图片。
409	idempotency_conflict	否	Idempotency-Key 已用于另一个不同的请求体。
409	request_in_progress	否	使用该 Idempotency-Key 的第一个请求仍在运行。
413	payload_too_large	否	请求体或图片超过大小限制。
429	rate_limited	是	达到模型池的每分钟限制（已储值账户：仅当余额无法支付该调用时）。
429	daily_limit_reached	否	公共池的每日额度已用完。
500	internal_error	否	意外的服务器错误。
502	upstream_error	是	调用在处理阶段失败。
502	bad_model_output	否	模型返回了无法使用的结果。
503	model_unavailable	是	当前没有 GPU 节点提供该模型。唯一的节点短时失联（约一分钟内）时，只有交互式调用得到该错误，带 Retry-After: 5；同步和批量调用在队列中等待，直到各自的截止时间。
503	model_busy	是	模型队列已满，或预计等待时间过长。
503	unavailable	是	临时性资源紧张，例如图片处理繁忙或图片存储不可用时。
504	upstream_timeout	是	调用超过了截止时间。

导致 400 invalid_request 的约束按字段列于 API 参考。

daily_limit_reached 带有指向下一个 UTC 日的 Retry-After，但在此之前重复同一请求仍会失败。增加额度可获得更高限制。详见速率限制与模型池。

重试建议

• 仅当 retryable 为 true 时才重复调用。
• 下一次尝试前，至少等待 retryAfterMs（或 Retry-After 秒数）。model_unavailable 和 model_busy 没有提示时，服务器建议等待 5000 ms。
• 对会消耗额度的调用发送 Idempotency-Key，使重复的调用不会被重复扣费或重复运行。
• 遇到 404 image_not_found 时，重新上传图片，然后即可重复调用。
• 其他 4xx 错误须先修改请求或账户，再进行下一次尝试。

请求 ID

每个响应（包括错误响应）都带有 X-Request-Id 响应头：由服务器生成的 16 个随机十六进制字符。客户端发送的值会被忽略。成功的推理响应还在 id 字段中带有调用 ID（call_<uuid>）。联系支持时应提供其中任一值。

幂等性

对任何会消耗额度的 POST 请求，发送 Idempotency-Key: <1 至 128 个可打印 ASCII 字符>。

• 在同一账户内，密钥保留 24 小时。
• 使用相同密钥和相同请求体重复请求，会返回原始响应（状态码和响应体），并带有响应头 Idempotent-Replayed: true。该调用不会再次扣费，也不会再次运行。
• 相同密钥搭配不同请求体，返回 409 idempotency_conflict。
• 第一个请求仍在运行时使用相同密钥，返回 409 request_in_progress。
• 只保存最终结果：2xx 和永久性的 4xx。402、429 或 5xx 会释放该密钥，因此可以用同一密钥重试相同的请求。

curl https://api.stack.foldbun.com/v1/ocr \
  -H "Authorization: Bearer $FOLDBUN_API_KEY" \
  -H "Idempotency-Key: 6d1a8b3e-1f6e-4f0c-9d54-2b8f7c1e0a11" \
  -H "Content-Type: application/json" \
  -d '{"image": {"id": "img_2dedd0716bfd46ec29b286a279d18b6fc80631e5d90fedb5c63eb36f231622e6"}}'