平台

错误

错误以 JSON 返回，格式与调用的端点一致，包含便于人理解的错误消息；OpenAI 风格的端点还提供稳定的错误码，供程序处理。

响应结构

OpenAI 风格的端点
{
  "error": {
    "message": "This API key can't use `gpt-6-astra`. It's limited to gpt-6-sol. Change that at https://zurelay.com/app/keys.",
    "type": "permission_error",
    "param": "model",
    "code": "model_not_allowed"
  }
}

在 /v1/messages 上，同样的错误会按 Anthropic 格式返回，不含错误码：请使用 HTTP 状态码和 error.type: { "type": "error", "error": { "type": "...", "message": "..." } }。每个聊天、图像和视频响应，无论是否出错，都包含 x-request-id 响应头。

错误码

状态代码处理建议
400invalid_request请修正请求：message 说明问题，param 指出问题所在。
400unsupported_content该模型无法读取这类文件。请移除文件，或选择支持此类文件的模型。
400invalid_url请求中的某个链接下载失败。message 中包含该链接返回的状态码。
400invalid_image输入图片无法使用（类型、大小或链接有问题）。
400image_not_generated模型拒绝了该提示词。不收费。
400context_length_exceeded模型提示对话过长。请缩短对话，或选择上下文更长的模型。
400max_tokens_reached非流式 /v1/messages 响应在工具调用过程中达到了 max_tokens，因此消息不完整。已生成的内容会计费。请提高 max_tokens 后重新发送。
401missing_api_key请通过 Authorization 或 x-api-key 传入密钥。
401invalid_api_key密钥错误或已被撤销。
401expired_api_key请创建新密钥。
402insufficient_quota余额扣除进行中请求的预留金额后，不足以支付此请求，或在生成回答的过程中耗尽。请在账单页面充值，或调低 max_tokens 以减少输出。如果自动充值已启动，message 中会有说明：请稍等几秒后重试。
402key_budget_exceeded计入进行中的请求后，此请求可能导致密钥超出月度预算，或已在执行过程中达到预算上限。请提高预算，或等到下个月。
402key_daily_budget_exceeded密钥的每日预算也适用相同规则。请提高预算，或等到 UTC 午夜。
403model_not_allowed此密钥无权使用该模型。
403ip_not_allowed此密钥仅允许从其他地址使用。
404model_not_found请在模型页面核对模型 ID。
404unknown_url端点不存在。请检查路径和基础 URL。
404video_not_found此工作区中没有该 ID 对应的视频。
404image_not_found此工作区中没有该 ID 对应的图片请求（GET /v1/images/{id}，适用于通过 callback_url 发起的请求）。
409video_not_ready视频尚未生成完成：请持续轮询，直到 status 为 completed。
409video_failed视频生成失败，没有可下载的内容。error 中说明了原因。
410video_expired视频已从素材库中删除，或已在 30 天到期后删除。
413too_large请求或文件超出大小限制。请通过链接发送大文件。
429rate_limit_exceeded请等待 retry-after 指定的秒数后重试。
429concurrency_limit_exceeded此工作区已有 32 个请求同时运行。请等待 retry-after 指定的秒数，待其中一个请求完成后重试。
500server_error我们这边出了问题。请重试。
502stream_interrupted作为中断流的最后一个事件发送。仅对中断前已传输的内容计费，中断后的内容不计费；请重试。
503model_unavailable模型暂时不可用。请等待 retry-after 指定的秒数后重试，或开启智能路由。如果没有 retry-after 且 x-should-retry: false，则表示模型可用，但每次处理此请求都会返回错误：请勿原样重发。
503server_restartingZurelay 正在重启处理此请求的机器。请立即重试：请求会由另一台机器接手。不收费，但如果流已开始，则与流中断时一样，仅对你已收到的内容计费。
503storage_unavailable图片已生成，但未能送达。不收费；请重试。
503service_unavailable我们这边出现了短暂故障。请重试。

重试

  • 遇到 429 和 503 时，请等待 retry-after 响应头指定的秒数（或采用指数退避）后重试，除非响应中注明 x-should-retry: false。
  • 其他 4xx 错误请勿原样重试：仍会因相同原因失败。
  • 失败的请求不收费，因此重试在成功前不会产生费用。中途中断的流按已传输的内容计费，少数带有 x-should-retry: false 的 503 则会收取输入费用（参见账单）。
  • OpenAI 和 Anthropic 的官方 SDK 已会自动重试适合重试的错误。

流式传输中的错误

模型针对请求本身返回的错误（例如不支持某个参数、提示词过长），会保留模型原始的错误消息和错误码，并以 400 或 422 状态码返回。

流式传输中的错误

流一旦开始，后续错误就无法再通过 HTTP 状态码返回。此时会发送最后一个错误事件（采用该端点的格式），然后结束流。仅对输入及错误前你已收到的输出计费，之后的内容不计费。这种情况很少见：大多数问题都会在首个 token 发出前被发现并重试。

如果余额或密钥预算在流式传输中途耗尽，流也会以同类事件结束，错误码为 insufficient_quota、key_budget_exceeded 或 key_daily_budget_exceeded。非流式请求若在中途耗尽余额或预算，会返回已生成的内容，像达到 max_tokens 时一样截断（finish_reason: "length"，或 /v1/messages 上的 stop_reason: "max_tokens"），并通过 x-zurelay-stopped 响应头注明错误码。

有疑问，或发现内容缺失？联系我们的支持团队，我们会通过邮件回复，通常只需一分钟。