状态码与错误

排查 API 请求时，应同时查看 HTTP 状态码、响应正文和响应头。不同上游协议的错误 JSON 结构可能不同，因此不要只依赖某一个嵌套字段。

快速判断

状态码	常见含义	首先检查
400	请求参数或 JSON 不符合接口要求	请求体、字段名、上下文长度、模型能力
401	鉴权失败	Key 是否完整、请求头类型是否正确
403	当前凭证无权执行请求	账户、分组、模型或内容限制
404	路径或模型不存在	Base URL、重复 /v1、模型 ID
408	请求超时	客户端超时、网络与请求规模
413	请求体过大	图片、音频、Base64 或长上下文
422	请求可解析但无法处理	参数组合与协议兼容性
429	请求过快或当前资源繁忙	限额、并发、重试间隔
5xx	网关或上游临时异常	状态公告、有限重试、请求上下文

这张表用于定位方向，不构成每个端点的固定错误契约。最终应以实际响应和控制台说明为准。

先做最小复现

将复杂请求缩减为只有模型和一条文本消息的请求：

curl -i https://flashcoding.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model-id",
    "messages": [
      {"role": "user", "content": "请只回复：连接成功"}
    ]
  }'

-i 会同时打印响应头。提交日志或截图前，务必遮盖 Authorization、x-api-key、Cookie 和任何个人数据。

如果最小请求成功，再逐项恢复工具调用、图片、结构化输出和采样参数。这样可以明确是哪一个字段引发错误。

400：请求无效

常见原因包括：

• JSON 中包含注释、尾随逗号或未转义的换行。
• 把 Chat Completions 的 messages 发给 Responses，或把 Gemini 的 contents 发给 OpenAI 路径。
• 使用了模型不支持的参数或角色。
• 输入或期望输出超过模型限制。
• 图片、音频或工具参数的结构不符合所选协议。

400 通常不会因为等待而自行恢复。修正请求后再试，不要原样循环重试。

401 / 403：鉴权或权限

按顺序检查：

1. Key 是否来自当前 FlashCoding.AI 账户，复制时是否带入空格或换行。
2. OpenAI 兼容接口是否使用 Authorization: Bearer ...。
3. Anthropic 原生接口是否使用 x-api-key。
4. Gemini 原生接口是否使用控制台要求的鉴权头。
5. Key 是否已被撤销，账户或分组是否允许访问目标模型。

真实密钥一旦出现在公开仓库、前端包或聊天记录中，应立即撤销并创建新 Key，而不是只删除暴露位置。

404：路径或模型

最容易忽略的是 Base URL 拼接：

正确的 SDK Base URL: https://flashcoding.ai/v1
常见错误:            https://flashcoding.ai/v1/v1

还要确认模型 ID 的大小写、连字符和版本后缀。不要根据供应商品牌名自行拼接；从控制台复制完整值。

429：限流与繁忙

429 可能来自账户限制、并发过高或上游临时繁忙。客户端应：

1. 优先遵循 Retry-After 等响应提示（如果返回）。
2. 使用带随机抖动的指数退避，例如逐步延长等待时间。
3. 设置最大重试次数和总时间预算。
4. 限制并发，并通过队列吸收突发流量。
5. 避免多个服务同时重试造成新的流量尖峰。

创建多个 Key 不代表限额会增加；实际限制维度以控制台规则为准。

5xx 与网络错误

先区分是否收到 HTTP 响应：

• 有 5xx 响应：保存状态码、时间、路径、模型和响应头，进行有限重试。
• 没有 HTTP 响应：检查 DNS、TLS、代理、出口防火墙和客户端超时。
• 流式中途断开：已输出内容可能不完整；除非业务能去重，否则不要盲目把整个请求重新提交。

对于可能产生副作用或重复费用的请求，重试前应评估幂等性，并始终设置明确的重试次数上限。

重试策略

情况	是否建议自动重试
400、401、403、404、422	否；先修正请求或权限
408 或连接中断	可以，需限制次数并判断幂等性
429	可以，遵循服务端提示并退避
500、502、503、504	可以，短暂退避且限制总时长

SDK 自带重试时，要把 SDK 重试与业务层重试合并计算，避免请求次数成倍增加。

联系支持前准备

提供以下信息能减少来回确认：

• 发生时间和时区。
• 请求路径、协议和模型 ID。
• HTTP 状态码与已脱敏的响应正文。
• 响应头中的请求标识（如果存在）。
• 可复现的最小请求，Key 用 sk-*** 替换。
• 客户端或 SDK 名称与版本，以及是否使用代理。

不要发送完整 API Key、账户密码、支付凭证或未经处理的用户数据。联系渠道见联系支持。