# HTTP 错误

> 统一错误包装、error.type 对照，以及提交结果待确认时的处理。

<a id="apimart-errors-section-1"></a>

## 错误响应

失败 HTTP 响应示例：

```json
{
  "error": {
    "code": 400,
    "message": "unsupported parameter: callback_url",
    "type": "invalid_request_error"
  },
  "request_id": "request_example"
}
```

| HTTP | error.type | 常见原因 |
| --- | --- | --- |
| 400 / 413 / 422 | invalid_request_error | 型号未适配、字段不支持、类型错误、范围超限、冲突参数 |
| 401 | authentication_error | 虚拟密钥无效 |
| 402 | payment_required | 预算不足，以 message 为准 |
| 403 | permission_error | 没有模型权限、缺少企业预算身份，或使用平台管理账号的密钥 |
| 404 | not_found_error | 任务/产物不存在或不属于当前主体 |
| 409 | conflict_error | 结果尚不可读取等状态冲突 |
| 429 | rate_limit_error | 提交/读取限流，或主体图片队列满 |
| 502 / 503 / 504 | bad_gateway | 模型服务或平台异常，或提交结果待确认 |
| 其他错误状态 | server_error | 读取 message 和 request_id 定位 |

视频提交结果未确认时，503 响应可能带有：

```json
{
  "error": {
    "code": 503,
    "type": "bad_gateway",
    "message": "provider submission requires reconciliation; do not resubmit"
  },
  "task_id": "task_example",
  "reconciliation_required": true,
  "request_id": "request_example"
}
```

此时保存 task_id 和 request_id，通过查询原任务或联系平台确认，不要重发 POST。异步图片在模型服务响应不完整或超时时，也可能保持 processing 并带 reconciliation_required；这不等于生成失败或免费。