响应格式由端点决定
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 不再透传供应商的状态码、错误码或消息。
- 供应商侧故障:
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
HTTP401
参数:原生请求
HTTP400
预算:估算超出上限
HTTP402
幂等:请求已完成
HTTP409
幂等:Similarweb 兼容格式
HTTP409
上游:原生转发传输失败(标准信封以外)
HTTP502
上游:托管产品传输失败
HTTP503
依赖:计费依赖超时
HTTP503; X-Request-ID: example-request-id
配置:计费配置无效
HTTP503
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 错误不符合上述示例时,保留原状态和响应。