跳转到主要内容

响应格式由端点决定

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 不再透传供应商的状态码、错误码或消息。
此示例只说明信封形状,请求 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;请把客户端超时设得略高于该值。未公布该字段的操作没有固定的作答时限。

公开错误码迁移

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

六类诊断信息

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

未携带凭据的请求

未携带任何 AISA 凭据的请求只会得到两种结果之一,由路由决定,与 HTTP 方法无关。2026-10-20 实测: 无凭据时的 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

参数:原生请求

HTTP 400

预算:估算超出上限

HTTP 402

幂等:请求已完成

HTTP 409

幂等:Similarweb 兼容格式

HTTP 409

上游:原生转发传输失败(标准信封以外)

HTTP 502

上游:托管产品传输失败

HTTP 503

依赖:计费依赖超时

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

配置:计费配置无效

HTTP 503
费用报价模式的认证错误使用 error 内含 code、message 的对象,与上方顶层认证格式不同。已提供 API Key 的校验失败还会返回 request_id;缺少凭据时的拒绝可能不含该字段。请保留实际返回的 ID,不要要求每次报价拒绝都必须有 ID。处理该模式时请遵循端点的报价契约。 已报告费用的含义见已结算调用费用;标准信封以外,错误响应或费用头缺失都不能证明扣费为零。在标准信封中,错误响应的费用头为 0 即表示已确认未扣费。

重试指南

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

获取帮助

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