SupaNexus
开始使用

错误处理

Markdown 版本

示例中的 <BASE_URL> 请从 接入点 选择并替换。

SupaNexus API（/v1/*）错误响应采用 OpenRouter 兼容格式：error.code 为 数字，与 HTTP 状态码一致。

错误 JSON 格式

{
  "error": {
    "code": 402,
    "message": "Your account or API key has insufficient credits. Add more credits and retry the request.",
    "metadata": {}
  }
}
字段说明
error.code整数，等于 HTTP 响应 status
error.message人类可读描述
error.metadata可选扩展（如 provider 错误详情）

HTTP 状态码参考

HTTP场景
400参数无效、JSON 解析失败；video_url 非公网 http(s)（含 data URI / file / 厂商私有 scheme）
401API Key 缺失、错误或过期
413请求体超过上限（默认 64 MB，error.code = request_too_large）
402账户/API Key 余额不足
403账号已封禁，或权限不足 / 缺少组织/项目上下文
404模型不存在或不可售卖
408请求超时
409幂等 Key 重复使用
429速率或用量配额超限（可能有 Retry-After）
501Embeddings / Images 尚未实现
502服务暂时不可用
503服务暂时不可用
500服务内部错误

账号封禁（403）

平台用户被管理员封禁后，所有 /v1/* 请求在 API Key 校验通过后返回：

{
  "error": {
    "code": 403,
    "message": "Your account has been suspended. Contact support for assistance."
  }
}
  • 与 Key 是否有效无关（Key 未销毁时仍可能返回此错误）
  • 解封后立即恢复，无需重新创建 Key
  • 详见 认证 — 账号封禁校验

重试建议

HTTP是否重试说明
401否修正 API Key
403否账号封禁时联系管理员；其它 403 检查权限与上下文
402否充值或联系平台管理员
404否使用有效 model id
408视情况缩短 payload 或增加客户端超时
409否使用新的 Idempotency-Key
429是遵守 Retry-After
502视情况指数退避后重试
503视情况短间隔退避

服务认证失败

推理服务认证失败时，SupaNexus 通常返回 502，消息为 "Upstream authentication failed."，不暴露服务商细节。

Anthropic /v1/messages 错误

POST /v1/messages 返回 Anthropic 形态 JSON，而非 OpenRouter 数字 code：

{
  "type": "error",
  "error": {"type": "authentication_error", "message": "Invalid API key"}
}

详见 Messages。Chat Completions 仍使用上文 OpenRouter 格式。

流式错误

流开始前的错误使用上述 JSON 格式与对应 HTTP 状态码。见 流式响应。

相关