错误 | OpenModels Documentation

OpenModels 通过 Alephant gateway 返回兼容 OpenAI 的 JSON 错误。使用 HTTP status code 做宽泛处理，并在响应包含稳定的机器可读代码时使用 error.code。

错误响应格式

OpenModels 账号、billing 和 usage 错误可能包含 request_id 和 retryable 字段：

{
  "error": {
    "message": "KeyMarket account has insufficient available balance",
    "type": "key_market_error",
    "param": null,
    "code": "key_market_insufficient_balance",
    "request_id": "km_0123456789abcdef",
    "retryable": false
  }
}

某些 gateway 或上游错误使用标准的兼容 OpenAI 结构，可能不包含 request_id 或 retryable：

{
  "error": {
    "message": "Invalid credentials",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

字段：

字段	描述
`error.message`	面向人的失败说明
`error.type`	错误族，例如 `key_market_error`、`invalid_request_error` 或 `server_error`
`error.param`	与错误相关的请求参数，或 `null`
`error.code`	可用时的机器可读错误代码
`error.request_id`	可用时用于调试和支持的请求标识符
`error.retryable`	可用时表示 gateway 是否认为该失败可以安全重试

对于 routed model 请求，如果你发送 x-request-id header，gateway 可以在 error.request_id 中回显它。否则，gateway 可能生成一个 km_... request id。早期 authentication、account 或上游错误可能不包含 request id，因此请在客户端日志中保留你自己的 request id。

错误代码

目前请处理这些响应：

HTTP status	Error code	含义	处理方式
401	`invalid_api_key`	API 密钥缺失、格式错误、无效、已撤销或不再启用。	检查 `Authorization: Bearer ...` header，创建或轮换 API 密钥，并用有效密钥重试。
402	`key_market_insufficient_balance`	账号没有足够可用 credits 来预留或完成请求。	增加 credits，确认余额 active，然后重试。
503	`key_market_usage_unavailable`	用量或支出数据暂时不可用，因此网关无法安全校验限制。	稍后退避重试。不要假设用量被计为零。
400	无代码或通用网关代码	请求无效、模型不受支持，或模型路由不可用。	根据模型页面检查请求 body、端点和模型 ID。
502, 503, 504	none, upstream body, or gateway code	上游供应商或路由失败、不可用或超时。	当 status 属于瞬时错误时退避重试，或切换到其他受支持模型。

OpenModels 专属 Key Market 代码可能出现在 gateway 响应中。出现时，请按如下方式处理：

HTTP status	Error code	含义	处理方式
401	`key_market_key_invalid`	OpenModels API 密钥缺失、格式错误、无效、已撤销或不再启用。	检查 `Authorization: Bearer ...` header，创建或轮换 API 密钥，并用有效密钥重试。
402	`key_market_insufficient_balance`	账号没有足够可用 credits 来预留或完成请求。	增加 credits，确认余额 active，然后重试。
403	`key_market_spend_limit_exceeded`	API 密钥已达到月度支出限制。	提高该密钥的月度限制，使用另一个启用的密钥，或等待月度用量窗口重置。
400	`key_market_model_not_available`	请求的模型无法通过 OpenModels 使用。	检查 Models 页面，并使用受支持的 model ID 发送请求。
400	`key_market_image_price_not_available`	请求的 image model、size、quality 或 image pricing 组合不可用。	使用受支持的 image pricing 选项或选择其他模型。
503	`key_market_no_upstream_available`	模型存在，但当前没有可用上游路由。	稍后退避重试或切换到其他受支持模型。
503	`key_market_usage_unavailable`	用量或支出数据暂时不可用，因此网关无法安全校验限制。	稍后退避重试。不要假设用量被计为零。
502	`key_market_upstream_not_supported`	所选上游不支持请求的端点或模型。	检查模型和端点组合，然后切换模型或端点。
502	`key_market_upstream_error`	上游供应商返回错误或在请求期间失败。	仅当 `error.retryable` 为 `true` 时重试；否则检查请求或切换模型。
504	`key_market_upstream_timeout`	上游供应商未在 gateway 超时前响应。	使用指数退避重试，减少请求大小，或切换到其他模型。

重试指南

当 error.retryable 存在时，将它作为主要重试信号。如果缺少 error.retryable，则回退到 HTTP status code 和你自己的幂等规则。

在用户或系统改变某些条件之前，不要自动重试这些错误：

invalid_api_key
key_market_key_invalid
key_market_insufficient_balance
key_market_spend_limit_exceeded
key_market_model_not_available
key_market_image_price_not_available
key_market_upstream_not_supported

这些错误可能是瞬时的。当 error.retryable 为 true，或你的 HTTP status 与幂等规则允许时，请使用退避重试：

key_market_no_upstream_available
key_market_usage_unavailable
key_market_upstream_error
key_market_upstream_timeout

没有 Key Market 代码的 HTTP 429、502、503 和 504 响应也可能是瞬时错误。重试时使用指数退避和较小的最大重试次数。生产工作负载中，请记录客户端请求 ID、可用时的 error.request_id、error.code、模型 ID、端点，以及请求是否为流式传输。

常见修复

错误	常见修复
密钥无效	创建新的 API 密钥，更新环境变量，并确保请求使用 `Authorization: Bearer <OM_API_KEY>`。
余额不足	在 OpenModels 控制台中增加积分。积分在受支持模型和 API 密钥之间共享。
支出限制已超出	提高该密钥的月度支出限制，或通过另一个启用的密钥路由流量。
Model not available	从 Models 页面复制 model ID 并更新 `model` 字段。
No upstream available	稍后重试或选择另一个具有 active availability 的模型。
Upstream timeout	减少 prompt 大小，降低 `max_tokens`，或使用退避重试。

处理示例

async function callOpenModels(request) {
  const response = await fetch("https://api.getopenmodels.com/v1/chat/completions", request);
  if (response.ok) {
    return response.json();
  }
  const body = await response.json().catch(() => null);
  const error = body?.error;
  const code = error?.code;
  if (response.status === 401 || code === "invalid_api_key" || code === "key_market_key_invalid") {
    throw new Error("OpenModels API key is invalid. Create or rotate the key before retrying.");
  }
  if (code === "key_market_insufficient_balance") {
    throw new Error("OpenModels credits are insufficient. Add credits before retrying.");
  }
  if (code === "key_market_spend_limit_exceeded") {
    throw new Error("OpenModels monthly spend limit has been reached for this key.");
  }
  const retryable =
    error?.retryable === true || [429, 502, 503, 504].includes(response.status);
  if (retryable) {
    throw new Error(`Retryable OpenModels error: ${code || response.status}`);
  }
  throw new Error(error?.message || `OpenModels request failed with ${response.status}`);
}

支持

报告错误时请包含：

你的 client request id
可用时的 error.request_id
可用时的 error.code
HTTP status
Model ID
Endpoint
请求是否为 streaming
Timestamp