> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastino.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use https://docs.fastino.ai/llms.txt to discover and navigate pages. Use https://docs.fastino.ai/llms-full.txt when you need the complete documentation corpus. Use https://docs.fastino.ai/openapi.json as the source of truth for customer-facing routes. For GLiDE decision inference, call POST https://api.fastino.ai/v1/systemone with model fastino/GLiDE. Do not infer undocumented routes. Read API keys from FASTINO_API_KEY and never embed credentials in code, logs, or reports.

# Fastino API 错误代码与响应格式

> Fastino API 返回的 4xx 与 5xx HTTP 状态代码、每种错误族的 JSON 响应结构,以及计费、速率限制与校验错误的解决步骤。

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

## 错误响应格式

大多数错误响应会返回包含 `detail` 字段的 JSON 主体：

```json theme={null}
{
  "detail": "..."
}
```

少数几类响应使用不同的结构：

* **计费拒绝**（`402`、部分 `403`）返回 `{"code", "message", "resolution_url"}` 而非 `detail`--参见下方的 [402](#402-需要付款-payment-required) 和 [403](#403-禁止访问-forbidden)。
* **预热响应**（`425`）包含 `Retry-After` 响应头。OpenAI 格式的响应体还带有 `code: "model_warming"`--参见下方的 [425](#425-过早-too-early)。
* **速率限制响应**（`429`）在 `detail` 之外增加 `code` 和 `scope` 字段，并附带 `X-RateLimit-Scope` 和 `X-RateLimit-Code` 响应头--参见下方的 [429](#429-请求过多-too-many-requests)。
* **未处理的服务器错误**（`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](mailto:support@pioneer.ai)。设置说明请参见[身份验证](/cn/authentication)。

***

### 402 - 需要付款 (Payment Required)

<Warning>
  `402` 响应表示您的账户没有可用的付费余额，或需要执行计费操作才能运行推理。在您充值或升级套餐之前，所有 API 调用都会失败。请前往 **Settings** → **Billing** 或参见[套餐和定价](/cn/pricing)来解决此问题。
</Warning>

您的账户余额不足以完成请求。响应主体的 `code` 字段会告诉您具体属于哪种情况--最常见的是 `out_of_credits`（您的赠送额度已耗尽且没有可用的付费余额）或 `direct_model_requires_credits`（直接调用受支持的模型需要付费额度余额）。

**如何修复：** 登录 [Fastino](https://agent.fastino.ai)，前往 **Settings** → **Billing**，充值或升级套餐。有关额度限制及超额计费的工作方式，请参见[额度限制和超额消费上限](/cn/api-reference/rate-limits#额度限制和超额消费上限)。

***

### 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 个

```json theme={null}
{
    "detail": "For 'POST /v1/training-jobs', ...",
    "errors": [...]
}
```

***

### 425 - 过早 (Too Early)

模型正在临时预热，尚未准备好提供推理服务。在一段时间没有流量后的首次请求，或首次请求新配置的按需部署时，这属于正常现象，并不代表你的请求有误。预热时间因模型而异，因此一个请求在成功之前可能会多次返回 `425`。

大多数端点返回带有 `code: "model_warming"` 的 OpenAI 格式响应体：

```json theme={null}
{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_warming"
  }
}
```

携带 `anthropic-version` 请求头的 `/v1/messages` 请求则会收到 Anthropic 格式的响应体，其中没有 `code` 字段：

```json theme={null}
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "..."
  }
}
```

| 响应头 | 值 |
| - | - |
| `Retry-After` | 下一次尝试前需要等待的秒数。这是重试延迟，并不保证模型届时已就绪。 |
| `x-should-retry` | OpenAI 格式响应中为 `true`，因此 OpenAI SDK 会自动重试。Anthropic 格式响应中为 `false`，因此 Anthropic SDK 不会重试，需要你自行处理。 |

**如何修复：** 等待 `Retry-After` 秒（如果缺少该响应头则等待 30 秒），然后重新发送相同的请求，并限制重试次数。以下每个示例最多重试 5 次，设置 300 秒的客户端超时，遇到其他非 2xx 响应时停止。同样的循环也适用于 `/v1/systemone`，只需更改 URL 和请求体。

<CodeGroup>
  ```bash cURL theme={null}
  for attempt in 0 1 2 3 4 5; do
    http_code=$(curl -sS --max-time 300 -o response.json -D headers.txt -w "%{http_code}" \
      https://api.fastino.ai/v1/chat/completions \
      -H "Authorization: Bearer $FASTINO_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "fastino/gliner2.5-multi-v1",
        "messages": [{ "role": "user", "content": "Apple announced the MacBook Pro at WWDC in Cupertino." }],
        "schema": { "entities": ["organization", "product"] }
      }')
    [ "$http_code" = "425" ] && [ "$attempt" -lt 5 ] || break
    delay=$(awk 'tolower($1) == "retry-after:" && $2 + 0 > 0 { print $2 + 0 }' headers.txt)
    sleep "${delay:-30}"
  done

  if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
    cat response.json
  else
    echo "Request failed with HTTP $http_code: $(cat response.json)" >&2
  fi
  ```

  ```python Python theme={null}
  import os
  import time
  import requests

  MAX_RETRIES = 5

  for attempt in range(MAX_RETRIES + 1):
      response = requests.post(
          "https://api.fastino.ai/v1/chat/completions",
          headers={"Authorization": f"Bearer {os.environ['FASTINO_API_KEY']}"},
          json={
              "model": "fastino/gliner2.5-multi-v1",
              "messages": [
                  {"role": "user", "content": "Apple announced the MacBook Pro at WWDC in Cupertino."}
              ],
              "schema": {"entities": ["organization", "product"]},
          },
          timeout=300,
      )
      if response.status_code != 425 or attempt == MAX_RETRIES:
          break
      retry_after = response.headers.get("Retry-After", "")
      time.sleep(int(retry_after) if retry_after.isdigit() else 30)

  if not 200 <= response.status_code < 300:
      raise RuntimeError(f"Request failed: {response.status_code} {response.text}")
  print(response.json()["choices"][0]["message"]["content"])
  ```

  ```javascript JavaScript theme={null}
  const MAX_RETRIES = 5;
  let response;

  for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
    response = await fetch("https://api.fastino.ai/v1/chat/completions", {
      method: "POST",
      headers: {
        Authorization: `Bearer ${process.env.FASTINO_API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        model: "fastino/gliner2.5-multi-v1",
        messages: [{ role: "user", content: "Apple announced the MacBook Pro at WWDC in Cupertino." }],
        schema: { entities: ["organization", "product"] },
      }),
      signal: AbortSignal.timeout(300_000),
    });
    if (response.status !== 425 || attempt === MAX_RETRIES) break;
    const retryAfter = Number(response.headers.get("Retry-After"));
    await new Promise((resolve) => setTimeout(resolve, (retryAfter || 30) * 1000));
  }

  if (!response.ok) {
    throw new Error(`Request failed: ${response.status} ${await response.text()}`);
  }
  const completion = await response.json();
  console.log(completion.choices[0].message.content);
  ```
</CodeGroup>

使用 SDK 时，请参阅[重试和模型预热](/cn/troubleshooting/retries)，了解应重试哪些响应以及如何退避。

***

### 429 - 请求过多 (Too Many Requests)

您已超出该端点的请求速率限制。响应包括一个 `Retry-After` 响应头，以及 `X-RateLimit-Scope` 和 `X-RateLimit-Code` 响应头，用于标识您触发了哪项限制--JSON 主体在 `detail` 之外携带对应的 `code` 和 `scope` 字段。

**如何修复：** 遵循 `Retry-After` 的值并在重试前退避等待。按端点划分的限制以及重试代码模式请参见[速率限制](/cn/api-reference/rate-limits)。请注意，额度和超额拒绝返回的是 `402`/`403`，而不是 `429`--请参见[额度限制和超额消费上限](/cn/api-reference/rate-limits#额度限制和超额消费上限)。

***

### 451 - 因法律原因不可用 (Unavailable for Legal Reasons)

由于您所在地区的出口管制或制裁限制，请求的模型不对您的账户开放。

**如何修复：** 请参见 [FAQ](/cn/faq) 获取当前受限地区列表和特定提供商的政策。如果您认为访问被错误地限制，请联系支持团队。

***

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

Fastino 服务器发生意外错误。这并非由您的请求引起。响应主体使用 `error` 和 `message` 字段，而不是 `detail`：

```json theme={null}
{
  "error": "Internal server error",
  "message": "..."
}
```

**如何修复：** 稍等片刻后重试。如果错误持续，请查看 [status.pioneer.ai](https://status.pioneer.ai) 获取实时服务状态或联系支持团队。

***

### 503 - 服务不可用 (Service Unavailable)

请求所需的依赖项--计费验证，或某个提供商的状态/指标端点--暂时不可用。

**如何修复：** 稍等片刻后重试。如果错误持续，请查看 [status.pioneer.ai](https://status.pioneer.ai) 获取实时服务状态或联系支持团队。

***

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

`POST /v1/messages` 会在上游 Claude 容量暂时饱和时，镜像 Anthropic 自身的 `overloaded_error` 响应。

**如何修复：** 使用退避策略重试，与处理 `429` 或 `503` 的方式相同。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.