计费与幂等

通过幂等键与追踪 ID 保证结算安全与可追溯。钱包与限额概念见 钱包 · 配额。

我想…	去这里
充值 / 限额	控制台 · 充值与账单
错误码	错误码

核心概念

机制	请求头	说明
结算幂等	X-Idempotency-Key	同一工作区内相同键仅首笔成功扣费，重复返回 409。重试须保持键不变。
追踪 ID	X-Request-Id	排障关联日志；响应中回传。
结算键反馈	X-Settlement-Key	实际结算键；未传幂等键时由服务端生成。

X-Idempotency-Key 工作原理

1. 首次请求：以该键结算。
2. 重复请求：同工作区同键 → 不二次扣费，返回 409。
3. 未传：服务端生成 UUID；无键重放可能重复扣费。

规则：仅在同一工作区内生效；每笔逻辑请求唯一；重试不换键；建议 UUID。

响应头

响应头	说明
X-Request-Id	追踪 ID
X-Settlement-Key	实际结算键
X-Conversation-Id	有传入会话 id 时才有

重试边界

可安全重试（保持同一键）

场景	做法
超时 408	保持键重试
5xx	保持键重试
429	按 Retry-After 等待后保持键重试

不可沿用原键

场景	说明
400	改请求体后用新键
401 / 403	修好鉴权/权限后用新键
402	充值后用新键
409	该键已结算；除非刻意新扣费，否则不要当失败重试

错误码

HTTP	code	说明
402	insufficient_balance	余额不足
409	settlement_key_already_used	幂等键已在本工作区使用过

请求示例

curl -sS "${TRINITY_BASE_URL}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "你好"}],
    "max_tokens": 64
  }'

curl -sS -D - "${TRINITY_BASE_URL}/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${TRINITY_API_KEY}" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"hello"}],"max_tokens":16}' \
  -o /dev/null | grep -i x-request-id

最佳实践

1. 可能重试或重复提交时，始终传 X-Idempotency-Key。
2. 使用 UUID 或等价唯一标识。
3. 超时 / 5xx / 429 重试不换键。
4. 日志记录 X-Request-Id、X-Settlement-Key。
5. 将 409 视为「该键已结算」，而非笼统服务故障。

相关

• 请求参数
• Key 与模型权限
• 错误码
• 获取价目