鉴权与错误码

鉴权方式

所有客户接口使用 HTTP Bearer：

Authorization: Bearer <token>

两类 token：

类型	形式	用途
企业 key	agw_ 前缀	客户接入唯一正式方式。绑定组织与产品 scope，计费、限流、人级对账都挂在它上面
内部直连 key	运维配置的环境变量	仅网关运营方内部调试/冒烟，不计费、不归属组织，不对客户发放

agw_ key 的 scope 与接口对应关系：

scope	可访问接口
text	POST /v1/chat/completions
image	POST /v1/images/generations、POST /v1/images/tasks、GET /v1/images/tasks/{id}
search	POST /v1/searches

GET /v1/models 无需鉴权。

错误码

状态码	含义	处理建议
401	缺少或无效的 Bearer token	检查 key 是否正确、是否已被吊销
402	组织服务额度余额不足	响应体含 balanceMicrounits 当前余额；联系运营方充值。请求未转发上游，不计费
403	key 没有该产品 scope	换用带对应 scope 的 key，或联系运营方加 scope
404	模型别名不存在或未启用	以 GET /v1/models 返回为准
429	超出 key 或线路的 RPM/TPM 限额	退避重试；持续触发请联系运营方调整限额
502 / 503 / 504	上游供应商故障	网关已按线路优先级自动重试/切换后仍失败；可重试

402 响应示例：

{
  "detail": {
    "message": "Insufficient service credits",
    "balanceMicrounits": -1200,
    "currency": "CNY"
  }
}

高可用行为（对调用方透明）

同一个对外模型别名背后可配置多条供应商线路：请求按优先级分组（数字小者优先），组内按权重分流；可重试的上游错误（连接失败、429、5xx、超时）自动切换下一条线路，不会重复计费。流式请求只在首个数据块之前允许切换。