错误码
Trinity 网关返回 JSON 错误体（如 error.message、error.type、error.code）。排障时请带上响应头 X-Request-Id / X-Settlement-Key。
| 我想… | 去这里 |
|---|---|
| 限流与 429 | 限流 |
| 模型权限 403 | Key 与模型权限 |
| 余额 / 幂等 | 幂等与结算 |
| 打开控制台 | 控制台 ↗ |
上游错误（可能透传）
| HTTP | 典型场景 | 建议 |
|---|---|---|
| 429 | 上游限流 | 指数退避 |
| 502 / 503 / 504 | 上游不可用或超时 | 有限次重试 |
| 401 / 403 | 上游密钥或权限（若供应商返回） | 核对模型权限并联系支持 |
INFO
对 429 / 5xx，Trinity 会尽量保留可解析错误体，便于 SDK 重试。字段可能因上游略有差异。
网关错误
| HTTP | 典型场景 | 建议 |
|---|---|---|
| 400 | 请求非法（model、类型、模态不匹配等） | 对照参数表 |
| 401 | 缺少或无效 Authorization | 检查 API Key / Bearer |
| 402 | 余额或额度不足 | 充值 |
| 403 | 权限不足、模型未开通、Key 限制、子区限额 | 模型权限 / 配额 |
| 404 | 模型 / 任务不存在或路径错误 | 核对模型 ID、taskId、URL |
| 408 | 生图同步等待超时 | 用 trinity_task.task_id 查任务 |
| 409 | 幂等键已使用 | 见 幂等与结算 |
| 429 | 网关或账户 / Key 限流 | 限流 |
| 529 | 上游过载、线路用尽（upstream_overloaded） | 有限次退避重试并记 Request ID |
| 5xx | 网关或上游临时异常 | 有限次重试并记 Request ID |
常见 error.code
鉴权与权限
| HTTP | error.code | 说明 | 建议 |
|---|---|---|---|
| 401 | invalid_api_key | Key 无效或已撤销 | 控制台 · API 密钥 ↗ 重建 |
| 403 | model_not_allowed | Key / 工作区无权 Call | Key 与模型权限 |
| 403 | workspace_quota_exceeded | 子区消费限额用尽 | 充值与账单 |
限流
| HTTP | error.code | 说明 | 建议 |
|---|---|---|---|
| 429 | user_tpm_limited | 用户 TPM（每分钟 token）达到上限 | 降低速率；有 Retry-After 则按其等待 |
| 429 | user_rpm_limited | 用户 RPM（每分钟请求数）达到上限 | 降低速率；有 Retry-After 则按其等待 |
这些是账户 / 工作区 / Key 维度的用户级限流，区别于上游透传的 429。详见 限流。
结算与幂等
| HTTP | error.code | 说明 | 建议 |
|---|---|---|---|
| 402 | insufficient_balance | 钱包不足 | 充值后用新幂等键重试 |
| 409 | settlement_key_already_used | 幂等键已结算 | 查原结果；新请求用新键 |
请求与模型
| HTTP | error.code | 说明 | 建议 |
|---|---|---|---|
| 400 | invalid_request | 参数问题 | 对照端点参数表 |
| 400 | model_modality_mismatch | 模态与模型不匹配 | 换模型或改请求 |
| 400 | model_interface_not_supported | 模型不支持该入口协议（如 Codex 对某模型用 /responses） | 核对模型支持的协议；详情见 模型列表 text_interfaces |
| 404 | model_not_found | 未启用 / 不存在 / hidden 未授权 | 模型广场 ↗ |
任务与上游
| HTTP | error.code | 说明 | 建议 |
|---|---|---|---|
| 400 | content_policy_violation | 内容审核 | 调整 prompt / 素材 |
| 404 | task_not_found | 生视频 / 生图任务不存在或无权限 | 核对 taskId |
| 404 | asset_not_found | 视频素材不存在或无权限 | 核对素材 ID |
| 408 | generation_timeout | 同步轮询超时 | 用 task id 查终态 |
| 502 | upstream_task_failed | 上游任务失败 | 查参数；失败通常不扣费 |
| 502 | upstream_search_unavailable | Web Search 上游未返回服务器检索结果 | 稍后重试；记 X-Request-Id |
| 503 | web_search_unavailable | Web Search 服务暂不可用 | 稍后重试 |
| 529 | upstream_overloaded | 上游过载，线路已用尽 | 有限次退避重试；记 X-Request-Id |
排查清单
TRINITY_BASE_URL含/v1，与 快速入门 一致。model为平台模型 ID（API 概述）。- Key 有 Call 权限（Key 与模型权限）。
- 联系支持时附上
X-Request-Id、X-Settlement-Key。