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

错误响应格式

大多数同步 API 错误使用统一的嵌套 error 封装结构:
校验失败使用相同的封装结构,并在 error 内额外包含一个 errors 数组。每一项通过 location 和 raw_location 标识无效字段,并在 message 中说明失败原因。 部分端点族有意使用不同的结构:
  • 计费拒绝(402、部分 403)返回 {"code", "message", "resolution_url"} 而非嵌套封装,参见下方的 402 和 403。
  • 预热响应(425)包含 Retry-After 响应头。OpenAI 格式的响应体还带有 code: "model_warming",参见下方的 425。
  • 速率限制响应(429)在 detail 之外增加顶层 code 和 scope 字段,并附带 X-RateLimit-Scope 和 X-RateLimit-Code 响应头,参见下方的 429。
  • 未处理的服务器错误(500)返回 {"error", "message"},而不是嵌套封装。
  • 携带 anthropic-version 请求头的 /v1/messages 请求会收到 Anthropic 格式的 {"type": "error", "error": {"type", "message"}} 封装。

交互式 future 失败

HTTP 4xx 表示服务器在排队前拒绝了交互式调用。成功排队会返回 future_id。轮询到 completed、failed 或 cancelled。已排队的 future 可能以 status: "failed" 和 error.message 结束;将 error.category 视为不透明字符串,而不是重试规则。

状态代码

400 - 请求无效 (Bad Request)

请求本身格式错误—JSON 无效,或查询/路径参数类型有误。当输入通过了 schema 校验但无法处理时,推理端点也会返回 400,例如 GLiDE 提示词超出上下文窗口,或图片超出 GLiDE 图片限制。 如何修复: 确认请求主体为有效 JSON,并且查询/路径参数与端点参考文档中记录的类型一致。对于推理输入,请阅读 error.message 并修正其指出的输入。

GLiDE 图片错误

当 state 中的图片有问题时,POST /v1/systemone 会返回以下 400 响应。每个响应都使用嵌套信封,带有 "type": "invalid_request_error" 和 "code": null,因此请按 error.message 匹配:
缺少 image_url.url 的 image_url 部分会在 schema 校验时失败,返回 422,消息为 image_url parts require an image_url.url.

401 - 未授权 (Unauthorized)

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

402 - 需要付款 (Payment Required)

402 响应表示您的账户没有可用的付费余额,或需要执行计费操作才能运行推理。在您充值或升级套餐之前,所有 API 调用都会失败。请前往 Settings → Billing 或参见套餐和定价来解决此问题。
您的账户余额不足以完成请求。响应主体的 code 字段会告诉您具体属于哪种情况—最常见的是 out_of_credits(您的赠送额度已耗尽且没有可用的付费余额)或 funding_required(您的账户从未充值)。spend_limit_reached 表示您的团队或项目已达到每日或每月支出上限,billing_required 表示需要先完成账单操作才能运行推理。 如何修复: 登录 Fastino,前往 Settings → Billing,充值或升级套餐。如果是 spend_limit_reached,请在账单设置中提高上限,或等待周期重置。有关套餐和额度的详细信息,请参见套餐和定价。

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)

请求主体未通过验证。必填字段缺失、字段类型错误,或值超出可接受范围。 如何修复: 查看 error.message 以及 error.errors 中的条目,确定校验失败的字段。常见原因包括:
  • 在 POST /v1/training/jobs 中省略了 model 或 type
  • 在 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。
由于您所在地区的出口管制或制裁限制,请求的模型不对您的账户开放。 如何修复: 如果您认为访问被错误地限制,请联系支持团队。

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

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

503 - 服务不可用 (Service Unavailable)

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

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

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