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

> ## Agent Instructions
> - Base URLs: models `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`); data APIs `https://api.aisa.one/apis/v1`. The `servers` of each operation in https://aisa.one/openapi.yaml is authoritative.
> - Auth: `Authorization: Bearer $AISA_API_KEY`. Never print, log, or commit the key.
> - MCP (preferred for agents): `https://mcp.aisa.one/mcp`, signed in with OAuth, so there is no key to paste.
> - Agent Skill: `npx skills add AIsa-team/agent-skills --skill aisa`. Fallback with the AIsa CLI: `aisa skills install aisa`.
> - Spending: docs, https://aisa.one/models, https://aisa.one/api, `/v1/models`, and MCP `search`, `list_categories`, `get_details`, `batch_quote`, and the `account` operation are free. Quote the exact calls before running them (MCP `batch_quote`, CLI `aisa quote --json`). If the quote reports `auto_execute_eligible: true`, run it unless the user set a tighter limit or asked only for a quote. Otherwise, tell the user in one message the planned calls, the quoted price, and a total USD budget for the task, then wait for approval. Direct HTTP calls follow the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback. Do not make paid calls to test availability. Full rule: https://aisa.one/llms.txt

# 错误代码

> Integration API 的错误格式、六类诊断信息和安全重试指南。

## 响应格式由端点决定

Integration API 保留多种兼容错误格式。`error` 可以是字符串或对象；机器可读的 `code` 可能位于顶层，也可能位于该对象内。不要要求每个错误都包含 `type`、`code` 或 `request_id`。使用下文“标准错误信封”的操作，`error` 一定是对象。

下方示例说明网关生成的 Integration API 错误。OpenAI 兼容端点和 Anthropic 兼容端点各自遵循对应协议。标准信封以外，普通 Provider 响应可能保留上游状态码、正文和内容类型，包括非 JSON 错误。解析响应前请先检查 HTTP 状态码和内容类型。

排查问题时，请保留响应返回的 `X-Request-ID`，以及正文中存在的 `request_id`。它们是否存在、出现在哪里取决于错误路径；示例不保证每次拒绝都同时包含两者。使用标准信封的操作，AIsa 写出的每个错误都同时带有两者，且两者相同。

## 标准错误信封

部分 Integration API 操作使用统一的标准错误信封，可以从正文识别：`error` 是对象，并带有 `code`、`message`、`retryable`、`retry_hint` 和 `request_id`。在这些操作上，AIsa 不再透传供应商的状态码、错误码或消息。

```json theme={null}
{
  "error": {
    "code": "service_unavailable",
    "message": "Service temporarily unavailable.",
    "retryable": true,
    "retry_hint": "after_delay",
    "request_id": "example-request-id"
  }
}
```

此示例只说明信封形状，请求 ID 为示意值。

* **供应商侧故障：`503 service_unavailable`。** 供应商侧的各类故障对外是同一个答复：限流、临时不可用、超时、上游错误、响应无法使用，以及 AIsa 自己在上游的账户问题。下一步怎么做看 `retry_hint`。消息文本固定，不说明具体原因。
* **请求错误：`400 invalid_request`。** 请求本身有误时返回 `400`：网关契约校验未通过，或数据源拒绝了请求的输入。已知时 `param` 指出该参数（一定是你发送的参数或路径参数）；已知时，`missing` 和 `unsupported` 会列出相关参数。
* **未找到：`404 not_found`。** 查询已完成但没有结果，例如资料、人员或公司不存在。原样重试没有帮助。不扣费。
* **无法访问：`403 target_not_accessible`。** 目标存在，但为私密或受限。原样重试没有帮助。
* 以上三种情况，`message` 都是 AIsa 的固定文本，`retryable` 为 `false`，`retry_hint` 为 `never`。
* **不会返回 `502` 或 `504`。** 在这些操作上，AIsa 不会返回 `502` 或 `504`。不带 `X-Request-ID` 的 `502`/`504`，或 HTML、`application/problem+json` 错误页，来自 AIsa 前面的网络边缘，不是 AIsa 写出的，请等待片刻后重试。
* **请求 ID。** `X-Request-ID` 一定存在，且与 `error.request_id` 相同。它是不透明字符串，不要解析。预扣费用之前就被拒绝的请求，ID 可能以 `req_` 开头；之后的以 `imc_` 开头。
* **费用头。** 错误响应带 `X-AISA-Customer-Cost-Micros-USD: 0`，表示已确认本次请求未扣费。结果仍待对账时（`reconcile_first`）不带该响应头。
* **超时。** 操作公布了 `x-aisa-latency.timeout_seconds` 时，会在该秒数内作答，时间用完返回上面的 `503`；请把客户端超时设得略高于该值。未公布该字段的操作没有固定的作答时限。

| `retry_hint` | `retryable` | 含义与处理 |
| - | - | - |
| `after_delay` | `true` | 临时情况：限流、临时不可用、超时，或调用尚未发出。等待片刻后重试，使用带抖动、有次数上限的指数退避。 |
| `reconcile_first` | `false` | 调用已发出，结果和费用尚未确定。不要自动重发。用 `GET /v1/settlements/{request_id}`（即 `X-Request-ID`）查询结果；若发送过幂等键，也可用 `GET /v1/settlements?idempotency_key=<key>`。`state` 为 `pending`、`charged` 或 `not_charged`。 |
| `never` | `false` | 原样重试没有帮助。修正请求（`400`），或按失败处理。 |

### 公开错误码迁移

| 以前 | 现在（使用标准信封的操作） |
| - | - |
| 字符串信封 `{"error":"..."}` | 上面的对象信封 |
| `502` `provider request failed`、`provider response could not be accounted` 或 `provider response cannot be reconciled` | `503 service_unavailable` |
| `provider_unavailable`、`upstream_rate_limited`、`upstream_temporarily_unavailable`、`upstream_request_failed`、`provider_accounting_pending`、`provider_capacity_exhausted` 或供应商自己的错误码 | `503 service_unavailable`；用 `retry_hint` 区分 |
| 透传供应商的 `429` | `503 service_unavailable`，`retry_hint: after_delay` |
| 透传带供应商消息的 `4xx` | 查询无结果为 `404 not_found`；目标私密为 `403 target_not_accessible`；输入被拒为 `400 invalid_request`（已知时带 `param`）；其他拒绝为 `503 service_unavailable` |
| 错误响应不带费用头 | 已确认未扣费时为 `0`；待对账时不带 |

不使用标准信封的操作，仍按本页其余部分所述的格式返回。

## 六类诊断信息

| 类别 | 常见 Integration API 响应 | 处理方式 |
| - | - | - |
| 认证 | `401`：`missing_api_key`、`invalid_api_key`、`api_key_disabled` 或 `expired_api_key`；认证依赖失败可能返回 `503 authentication_unavailable` | 修正 AISA 凭据或排查认证依赖。 |
| 参数 | `400`，可能只有字符串错误；托管产品的参数校验可能返回结构化代码；标准信封使用 `400 invalid_request` 并带 `param` | 按端点契约修正请求。 |
| 预算 | `402`：`estimated_price_exceeds_max_price`、`insufficient_api_key_balance` 或 `insufficient_wallet_balance` | 检查花费上限和可用余额；估算不等于已结算费用。 |
| 幂等 | `409`：`request_in_progress`、`request_already_completed` 或 `idempotency_conflict`；Similarweb 保留带前缀的兼容代码 | 核查原操作，不要仅为绕过冲突而换用新键。 |
| 上游 | 标准信封：`503 service_unavailable` 并带 `retry_hint`，不会返回 `502` 或 `504`。其他操作：原生转发的传输失败可能返回 `502`；托管 Similarweb 的传输失败可能返回 `503 provider_unavailable`；Provider 响应可能透传 | 有 `retry_hint` 时按它处理；否则重复请求前确认是否已经转发或执行。 |
| 配置或依赖 | `503`：`metered_v2_billing_config_invalid`、`metered_v2_billing_dependency_timeout` 或 `metered_v2_billing_dependency_unavailable`；Similarweb 可能使用 `similarweb_billing_` 前缀 | 区分需要修复的配置和可恢复的临时依赖故障。 |

仅凭 `503` 不能判定为上游故障。`404` 可能指路由或上游资源；认证可能先于路由查找，因此缺少凭据不能证明路由不存在。`403`、`422`、`429` 的具体含义仍由端点决定，不要假定统一错误代码或限流响应头。在标准信封中，供应商限流返回 `503` 和 `retry_hint: after_delay`，不是 `429`。实际返回 `Retry-After` 时应遵守该值。

## 未携带凭据的请求

未携带任何 AISA 凭据的请求只会得到两种结果之一，由路由决定，与 HTTP 方法无关。2026-10-20 实测：

| 路由（无凭据） | 响应 |
| - | - |
| 带有按次机器支付（MPP）报价的路由，例如 `GET /apis/v1/fred/series`、`GET /apis/v1/agentmail/api-keys`、`POST /apis/v1/querit/search` | `402`，带 MPP 支付质询 |
| 其他所有路由，包括不存在的路径、`GET /v1/models`、`GET /v1/credits/balance`、其他数据路由（例如 `GET /apis/v1/similarweb/website-traffic-snapshot`、`POST /apis/v1/exa/search`）以及 `/v1` 模型路由（例如 `POST /v1/chat/completions`） | `401`，顶层 `code: missing_api_key` |
| 任意路由携带**无效** Key | `401`，`code: invalid_api_key` |

无凭据时的 `402` 表示网关提供按次 MPP 付费，并不表示余额不足：发送 AISA Key，或完成支付质询即可。`401 missing_api_key` 只表示没有发送凭据，不说明该路由是否存在。在报价模式（`X-AISA-Cost-Mode: quote`）下，认证错误是 `error` 内的对象，例如 `{"error":{"code":"invalid_api_key",...}}`。

不要把 `GET /v1/models` 成功当作业务访问可用的证明，它只验证传输。请用免费的受保护调用验证接入（HTTP 用 `GET /v1/credits/balance`，MCP 用 `account` 操作，CLI 用 `aisa balance`）。

## 文档与销售数据源的可用性

Website 的契约和销售数据端点单独报告来源可用性，不与 Integration API 的执行错误混淆。

核查已发布契约时，先读取 `https://aisa.one/api/contracts/version`。`contentHash` 标识 OpenAPI 字节，`docsRevision` 标识不可变的 Docs 输入。通过 `/api/contracts/source?hash=<contentHash>&bundled=1` 读取对应字节，或通过 `/api/contracts/source?hash=<contentHash>&operation_id=<operationId>` 读取单个操作。哈希不匹配返回 `409`；经过校验的打包内容不可用时可能返回 `503`。将响应的 `X-AISA-Contract-Hash`、`X-AISA-Docs-Revision` 与选定版本核对。`mode: formal` 描述打包的声明，不证明动态价格、可用状态或所有消费者都已更新。

标为 `pending` 的定义仍不完整。不要编造缺失的请求字段，也不要将不可用的请求定义视为可直接调用的完整契约。响应定义处于 pending 时仍属未知，即使现有端点可以调用。

销售 JSON 端点 `/api/sales-api-data` 无法取得经过校验的销售快照时，可能返回 HTTP `503`，其中 `freshness: unavailable`、`reason_code: verified_sales_source_unavailable`。这是文档/来源可用性结果，不能据此认定 Provider 请求已执行、认证失败或费用已结算。保留此前合格快照时，必须保留原始观测时间并明确显示 stale；不能将静态快照重新标为 fresh。恢复后先核对来源与发布身份，再将其视为当前数据。

## 网关实际格式示例

下方示例保留真实错误结构，请求 ID 仅作示意。

### 认证：API Key

HTTP `401`

```json theme={null}
{
  "code": "invalid_api_key",
  "error": "AISA API key is invalid. Check that you copied the complete key and are using an AISA key, not an upstream provider key.",
  "request_id": "example-request-id"
}
```

### 参数：原生请求

HTTP `400`

```json theme={null}
{
  "error": "request does not match the endpoint contract"
}
```

### 预算：估算超出上限

HTTP `402`

```json theme={null}
{
  "error": {
    "code": "estimated_price_exceeds_max_price",
    "message": "The estimated request price exceeds the configured maximum.",
    "retryable": false
  }
}
```

### 幂等：请求已完成

HTTP `409`

```json theme={null}
{
  "error": {
    "code": "request_already_completed",
    "message": "An identical request is already complete.",
    "retryable": false
  }
}
```

### 幂等：Similarweb 兼容格式

HTTP `409`

```json theme={null}
{
  "error": {
    "code": "similarweb_request_already_completed",
    "message": "An identical request is already complete.",
    "retryable": false
  }
}
```

### 上游：原生转发传输失败（标准信封以外）

HTTP `502`

```json theme={null}
{
  "error": "provider request failed"
}
```

### 上游：托管产品传输失败

HTTP `503`

```json theme={null}
{
  "error": {
    "code": "provider_unavailable",
    "message": "Similarweb is temporarily unavailable."
  }
}
```

### 依赖：计费依赖超时

HTTP `503`; `X-Request-ID: example-request-id`

```json theme={null}
{
  "error": {
    "code": "metered_v2_billing_dependency_timeout",
    "message": "The billing dependency timed out. Retry the request.",
    "request_id": "example-request-id",
    "retryable": true
  }
}
```

### 配置：计费配置无效

HTTP `503`

```json theme={null}
{
  "error": {
    "code": "metered_v2_billing_config_invalid",
    "message": "The Metering V2 billing configuration is invalid.",
    "retryable": true
  }
}
```

费用报价模式的认证错误使用 `error` 内含 `code`、`message` 的对象，与上方顶层认证格式不同。已提供 API Key 的校验失败还会返回 `request_id`；缺少凭据时的拒绝可能不含该字段。请保留实际返回的 ID，不要要求每次报价拒绝都必须有 ID。处理该模式时请遵循端点的报价契约。

已报告费用的含义见[已结算调用费用](https://aisa.one/docs/zh/api-reference.md#已结算调用费用)；标准信封以外，错误响应或费用头缺失都不能证明扣费为零。在标准信封中，错误响应的费用头为 `0` 即表示已确认未扣费。

## 重试指南

* 对于认证、参数和预算拒绝，先修正凭据、请求或花费限制，再重试。
* 错误带有 `retry_hint` 时按它处理：`after_delay` 等待后重试；`reconcile_first` 保留请求 ID、不要重发；`never` 不要原样重试。
* `retryable` 提示不保证原操作没有副作用、重试免费或端点支持幂等。重复 GET 或聊天请求也可能产生费用。
* 收到 `409` 时核查原操作，并遵循该端点的幂等规则。规则要求时保留同一键和请求正文；更换键可能创建第二次操作。
* 遇到临时故障，先确认重复执行安全。若有 `Retry-After` 则遵守它，否则使用带抖动且有次数和时间上限的指数退避。不要盲目重放执行结果不明的 Provider 创建操作或计费调用。
* 持续的配置错误需要运维排查，不能依靠无限重试解决。Provider 错误不符合上述示例时，保留原状态和响应。

## 获取帮助

向 [developer@aisa.one](mailto:developer@aisa.one) 提供大致 UTC 时间、HTTP 方法和公开路径、状态码、实际返回的错误代码（若有）、请求 ID（若有）和最小脱敏复现。不要附上 API Key 或其他凭据。


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