01
错误响应格式
所有非 2xx 响应统一这个 shape:
error response
{
"success": false,
"request_id": "req_a1b2c3d4...",
"error": {
"code": "INVALID_CODE_FORMAT",
"message": "代号格式不合法: 缺少 IDED 维度",
"details": {
"input": "I-A-L-X-AR(PR)-SE-LT"
}
}
}ADR-0001 C-6
error.message 和 details 永远不含 prompt 原文 / API key / 客户敏感数据. 只含错误类型 + 必要的诊断字段. 这是硬约束, 任何泄漏 → P0 修复.
02
14 个错误码
| code | HTTP | 含义 | 客户应对 |
|---|---|---|---|
| INVALID_CODE_FORMAT | 400 | 代号字符串格式不合法 | 校验后重发 |
| INVALID_LLM_CONFIG | 400 | llm_config 缺字段或非法 | 修 config 重发 |
| INVALID_SCORE | 400 | 量化分数超出 0-100 | 修分数重发 |
| INVALID_REQUEST | 400 | 请求体 schema 校验失败 | 看 details.errors |
| STREAM_NOT_SUPPORTED | 400 | stream=true 暂未支持 | 改 stream=false |
| UNSUPPORTED_MODEL | 400 | model 字段不在 hipmm/* 范围 | 用合法 model |
| INVALID_API_KEY | 401 | key 无效 / 已撤销 | 去控制台重新创建 |
| ENDPOINT_NOT_ALLOWED | 403 | 当前 plan 不支持该端点 | 升级 plan |
| BYOM_NOT_ALLOWED | 403 | Free / Starter 不支持 BYOM | 升级 Pro |
| SYMBOLIC_NOT_SUPPORTED | 422 | 象征版未覆盖该组合 | fallback 通俗版 |
| RATE_LIMIT_EXCEEDED | 429 | 触发分钟级限流 | 看 Retry-After 等待 |
| QUOTA_EXCEEDED | 429 | 月度配额用尽 | 升级套餐 / 等下月 |
| LLM_PROVIDER_ERROR | 502 | BYOM 客户的 LLM 出错 | 看客户自己 LLM |
| LLM_TIMEOUT | 504 | LLM 调用超时 (>300s) | 重试 (用 brief 档) |
| ENGINE_UNAVAILABLE | 503 | Engine 暂不可用 | 重试 + Retry-After |
| INTERNAL_ERROR | 500 | 未预期错误 (脱敏) | 联系支持 + request_id |
03
重试策略
客户 SDK 默认重试逻辑 (Python / TypeScript SDK 都自带):
| 状态码 | 默认行为 | 原因 |
|---|---|---|
| 5xx | 指数退避自动重试 2 次 | Engine 短暂故障 |
| 429 + Retry-After ≤ 10s | 按 Retry-After 重试 1 次 | 瞬时尖峰 |
| 429 + Retry-After > 10s | 不重试, 抛 RateLimitError | 持续过载, 用户决定 |
| 4xx (除 429) | 不重试, 抛对应异常 | 客户参数错 |
| timeout / network | 抛 APIConnectionError / APITimeoutError | 网络层, SDK 不重试 |
Python · 自定义重试
client = HiPMM(
api_key="hipmm_sk_...",
max_retries=3, # 默认 2
timeout=120.0, # 默认 60 秒
)04
request_id 用法
每次请求 (含错误) 返回 request_id. 联系客服时附上, 我们能在 Sentry / OTel trace / audit log 里精确定位.
Python
try:
client.codename.create("garbage")
except HiPMMError as e:
print(e.request_id) # req_a1b2c3d4...
# 联系 hello@hipmm.com 附上这个 id05
速率限制 headers
限流时 HiPMM 返回标准 headers:
response headers (429)
X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0 Retry-After: 60 X-Request-ID: req_a1b2c3d4...
客户可以按 Retry-After 等指定秒数再重试.