参考文档 · 错误

Photta API 错误所有错误类型及处理方式

一句话总结

每个 Photta API 失败响应均返回相同结构：状态码、`error.type`、说明信息以及 `request_id`。遇到 429 请在 Retry-After 标头指定的延迟后重试，遇到 5xx 请采用退避重试；400、401 和 402 请在业务代码中进行修复。

本页所有数据均来自 Photta API 文档 · 已验证 2026-09-10

错误类型

API 文档公布的完整列表。

状态类型含义

400invalid_request_error: The request is malformed or contains invalid parameters.
401authentication_error: The API key is missing, invalid, or expired.
402insufficient_credits_error: Your account does not have enough credits.
404not_found_error: The requested resource does not exist.
409conflict_error: The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error: Too many requests. Slow down and retry.Retry-After: 30
500api_error: An internal server error occurred. Retry later.

无论出现何种错误，每个 endpoint 都返回相同的响应外壳。

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded."
  },
  "request_id": "req_xxxxxxxx"
}

错误响应体结构是怎样的？

包含一个带有 `type` 和 `message` 的 `error` 对象，以及 `request_id`。类型字段是稳定且机器可读的；消息字段面向人类排查，可能会发生变化。

哪些错误值得重试？

在等待 Retry-After 指定秒数后的 429，以及配合指数退避重试的 5xx。400、401 或 402 会一直以相同方式失败，直到你修改了客户端的请求内容。

402 状态码代表什么？

`insufficient_credits_error`——账户没有足够的 credits 来完成该调用，或不足以覆盖批次中的全部预留额度。不会生成任何内容，也不会扣费。

如何报告调用失败？

发送 `request_id`、端点以及发生时间。这三元组能够唯一定位该次具体调用；排查时无需提供图像本身。

本页所有数据均来自 Photta API 文档 · 已验证 2026-09-10

生成 Photta API key，粘贴上方的 cURL 代码片段，咖啡还没煮好，你的第一张模特实穿图就已经生成完毕。