错误
Direct API 的每个错误代码、其含义以及是否应重试，包括付费调用返回 5xx 后该怎么做。
每个错误的响应体格式都相同。根据 HTTP 状态和 code 进行分支；向用户展示 description 或 error.message。
{
"description": "Human-readable explanation, safe to log.",
"code": "machine_readable_code",
"data": { "request_id": "…", "…": "…" },
"error": { "error_code": "…", "message": "…" }
}每个响应（无论成功还是出错）都带有 X-Request-Id。联系支持团队时请附上它。
错误代码
| HTTP | code | 含义 | 是否重试 |
|---|---|---|---|
| 400 | invalid_request | JSON 格式错误、请求体中有未知字段，或 input 未通过工具的 schema 校验（会逐一指出出错的字段） | 否，修正请求 |
| 401 | invalid_api_key | 密钥缺失、格式错误、已吊销或已过期 | 否 |
| 402 | insufficient_credits | 组织无法支付此次调用 | 充值后重试 |
| 402 | api_key_credit_limit_reached | 此次调用会超出密钥的每日、每月或总上限（data.period 说明是哪一个） | 在时间窗口重置或上限提高后重试 |
| 402 | subscription_paused | 组织的订阅已暂停 | 在订阅恢复后重试 |
| 402 | payment_required | 组织的订阅已逾期未付 | 在完成付款后重试 |
| 403 | direct_api_disabled | 此组织未开通 Direct API | 否，请联系 Morphic |
| 403 | insufficient_scope | 密钥缺少此工具所需的权限范围（data.required_scopes） | 否，请使用其他密钥 |
| 403 | plan_upgrade_required | 你的套餐不包含该模型或功能 | 否 |
| 403 | tool_not_available | 该工具会扣除积分，而你的组织尚未开启付费工具（data.tool 指出是哪个工具）；由你的 Morphic 联系人为你开启 | 否 |
| 403 | model_disabled_by_organization | 组织管理员关闭了此模型、分辨率或音频选项，并且没有为 API 允许它 | 否，请询问你的管理员 |
| 404 | not_found | 未知的工具、生成任务或 webhook，或超出此密钥访问范围的对象 | 否 |
| 409 | idempotency_conflict | Idempotency-Key 被用于不同的请求体或工具 | 否，请使用新键 |
| 409 | idempotency_in_progress | 使用此键的原始请求仍在运行 | 是，等待一秒后 |
| 409 | idempotency_outcome_unknown | 使用此 Idempotency-Key 的原始请求失败，或在可能已经运行之后始终没有响应，因此其结果未知 | 否：请先检查其结果，然后使用新键 |
| 413 | payload_too_large | 请求体超过 1 MB | 否 |
| 422 | tool_refused | 输入格式正确但无法运行；未扣除任何积分 | 否，请修改输入 |
| 429 | rate_limited | 触发了 速率限制 | 是，在 Retry-After 之后 |
| 500 | internal_error | 我们这边的问题 | 免费调用：是；付费调用：见下文 |
| 503 | service_unavailable | 临时过载或维护 | 免费调用：是，需退避；付费调用：见下文 |
| 504 | tool_timed_out | 工具未在 60 秒内响应；启动生成任务的调用可能仍已启动了它们 | 免费调用：是；付费调用：见下文 |
422 tool_refused 会指出字段、值以及可以使用的值；参见 工具拒绝。启动后才失败的生成任务会在 生成任务对象 上报告其自己的 error.error_code，扣除的积分会退还。
返回 5xx 的付费调用
返回 500、503 或 504 的付费调用，可能在失败前已经启动了工作并扣除了积分。使用相同的 Idempotency-Key 重试永远不会让它运行两次：重试会返回 409 idempotency_outcome_unknown。
- 检查该调用做了什么：
list_generations，或按时间筛选的GET /v1/direct/usage。 - 只为尚未启动的工作发送新的
Idempotency-Key。
如果完全没有收到响应（连接中断），请使用相同的键重试。你会得到已保存的响应，或者在它仍在运行时得到 409 idempotency_in_progress。参见 幂等性。
如果您遇到任何问题或有任何疑问，欢迎随时联系我们。我们很乐意提供帮助。请发送邮件至 support@morphic.com.