Skip to main content
Fastino API 使用标准 HTTP 状态代码来传达每次请求的结果。2xx 范围的代码表示成功。4xx 范围的代码表示您的请求存在可修复的问题。5xx 范围的代码表示服务器端问题。

错误响应格式

大多数错误响应会返回包含 detail 字段的 JSON 主体:
少数几类响应使用不同的结构:
  • 计费拒绝(402、部分 403)返回 {"code", "message", "resolution_url"} 而非 detail—参见下方的 402 和 403。
  • 预热响应(425)包含 Retry-After 响应头。OpenAI 格式的响应体还带有 code: "model_warming"—参见下方的 425。
  • 速率限制响应(429)在 detail 之外增加 code 和 scope 字段,并附带 X-RateLimit-Scope 和 X-RateLimit-Code 响应头—参见下方的 429。
  • 未处理的服务器错误(500)返回 {"error", "message"} 而不是 detail。
  • 针对 OpenAI 兼容端点(/v1/chat/completions、/v1/responses)的请求会收到 OpenAI 格式的 {"error": {"code", "type", "param", "message"}} 封装,而携带 anthropic-version 请求头的请求则会收到 Anthropic 格式的 {"type": "error", "error": {"type", "message"}} 封装,而非上述通用格式。

状态代码

400 - 请求无效 (Bad Request)

请求本身格式错误—JSON 无效,或查询/路径参数类型有误。 如何修复: 确认请求主体为有效 JSON,并且查询/路径参数与端点参考文档中记录的类型一致。

401 - 未授权 (Unauthorized)

您的请求未包含有效的 API 密钥、密钥已被撤销,或者您的账户因计费或欺诈审查而被封禁。 如何修复: 确认 X-API-Key 请求头存在并且包含您当前的密钥。如果您最近撤销了密钥,请在 Settings → API Keys 中生成新的密钥。如果您的账户被封禁,请联系 support@pioneer.ai。设置说明请参见身份验证。

402 - 需要付款 (Payment Required)

402 响应表示您的账户没有可用的付费余额,或需要执行计费操作才能运行推理。在您充值或升级套餐之前,所有 API 调用都会失败。请前往 Settings → Billing 或参见套餐和定价来解决此问题。
您的账户余额不足以完成请求。响应主体的 code 字段会告诉您具体属于哪种情况—最常见的是 out_of_credits(您的赠送额度已耗尽且没有可用的付费余额)或 direct_model_requires_credits(直接调用受支持的模型需要付费额度余额)。 如何修复: 登录 Fastino,前往 Settings → Billing,充值或升级套餐。有关额度限制及超额计费的工作方式,请参见额度限制和超额消费上限。

403 - 禁止访问 (Forbidden)

您的团队已达到套餐的最高月度超额支出(code: "credit_ceiling_reached"),或者您的账户需要经过验证的支付方式才能运行推理(code: "card_required")。 如何修复: 对于支出上限拒绝,请在 Settings → Billing 中升级套餐以提高上限。对于卡验证拒绝,请添加有效的支付方式。两类响应都包含直接指向解决页面的 resolution_url。

404 - 未找到 (Not Found)

您请求的资源不存在。当数据集名称、训练任务 ID、评估 ID、项目 ID 或模型 ID 拼写错误或已被删除时,可能会出现这种情况。 如何修复: 请仔细核对请求路径或主体中的 ID 或名称。使用相应的 GET 列表端点(例如 GET /v1/training-jobs、GET /v1/base-models)确认资源存在。

409 - 冲突 (Conflict)

模型在目录中存在但当前无法提供服务—例如,仅可用于训练的基础模型被请求用于直接推理,或者训练任务完成后按需部署尚未完成配置。 如何修复: 通过 GET /v1/base-models 查看模型的 supports_inference 和 supports_on_demand_inference,或等待部署完成配置后重试。

413 - 负载过大 (Payload Too Large)

请求主体—通常是评估或数据集的文件上传—超过了端点的大小限制。 如何修复: 查看端点参考文档中的上传大小限制,并在重试前拆分或压缩负载。

422 - 无法处理的实体 (Unprocessable Entity)

请求主体未通过验证。必填字段缺失、字段类型错误,或值超出可接受范围。 如何修复: 查看错误 message 中失败的具体字段。常见原因包括:
  • 在 POST /v1/training-jobs 中省略了 base_model
  • 在 label-existing 端点的 inputs 数组中发送的字符串少于 1 个或多于 1,000 个

425 - 过早 (Too Early)

模型正在临时预热,尚未准备好提供推理服务。在一段时间没有流量后的首次请求,或首次请求新配置的按需部署时,这属于正常现象,并不代表你的请求有误。预热时间因模型而异,因此一个请求在成功之前可能会多次返回 425。 大多数端点返回带有 code: "model_warming" 的 OpenAI 格式响应体:
携带 anthropic-version 请求头的 /v1/messages 请求则会收到 Anthropic 格式的响应体,其中没有 code 字段:
如何修复: 等待 Retry-After 秒(如果缺少该响应头则等待 30 秒),然后重新发送相同的请求,并限制重试次数。以下每个示例最多重试 5 次,设置 300 秒的客户端超时,遇到其他非 2xx 响应时停止。同样的循环也适用于 /v1/systemone,只需更改 URL 和请求体。
使用 SDK 时,请参阅重试和模型预热,了解应重试哪些响应以及如何退避。

429 - 请求过多 (Too Many Requests)

您已超出该端点的请求速率限制。响应包括一个 Retry-After 响应头,以及 X-RateLimit-Scope 和 X-RateLimit-Code 响应头,用于标识您触发了哪项限制—JSON 主体在 detail 之外携带对应的 code 和 scope 字段。 如何修复: 遵循 Retry-After 的值并在重试前退避等待。按端点划分的限制以及重试代码模式请参见速率限制。请注意,额度和超额拒绝返回的是 402/403,而不是 429—请参见额度限制和超额消费上限。
由于您所在地区的出口管制或制裁限制,请求的模型不对您的账户开放。 如何修复: 请参见 FAQ 获取当前受限地区列表和特定提供商的政策。如果您认为访问被错误地限制,请联系支持团队。

500 - 服务器内部错误 (Internal Server Error)

Fastino 服务器发生意外错误。这并非由您的请求引起。响应主体使用 error 和 message 字段,而不是 detail:
如何修复: 稍等片刻后重试。如果错误持续,请查看 status.pioneer.ai 获取实时服务状态或联系支持团队。

503 - 服务不可用 (Service Unavailable)

请求所需的依赖项—计费验证,或某个提供商的状态/指标端点—暂时不可用。 如何修复: 稍等片刻后重试。如果错误持续,请查看 status.pioneer.ai 获取实时服务状态或联系支持团队。

529 - 过载 (Overloaded)(仅适用于 Anthropic 兼容端点)

POST /v1/messages 会在上游 Claude 容量暂时饱和时,镜像 Anthropic 自身的 overloaded_error 响应。 如何修复: 使用退避策略重试,与处理 429 或 503 的方式相同。