响应格式由端点决定
Integration API 保留多种兼容错误格式。error 可以是字符串或对象;机器可读的 code 可能位于顶层,也可能位于该对象内。不要要求每个错误都包含 type、code 或 request_id。
下方示例说明网关生成的 Integration API 错误。OpenAI 兼容端点和 Anthropic 兼容端点各自遵循对应协议。普通 Provider 响应可能保留上游状态码、正文和内容类型,包括非 JSON 错误。解析响应前请先检查 HTTP 状态码和内容类型。
排查问题时,请保留响应返回的 X-Request-ID,以及正文中存在的 request_id。它们是否存在、出现在哪里取决于错误路径;示例不保证每次拒绝都同时包含两者。
六类诊断信息
仅凭
503 不能判定为上游故障。404 可能指路由或上游资源;认证可能先于路由查找,因此缺少凭据不能证明路由不存在。403、422、429 的具体含义仍由端点决定,不要假定统一错误代码或限流响应头。实际返回 Retry-After 时应遵守该值。
文档与销售数据源的可用性
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。处理该模式时请遵循端点的报价契约。
已报告费用的含义见已结算调用费用;错误响应或费用头缺失都不能证明扣费为零。
重试指南
- 对于认证、参数和预算拒绝,先修正凭据、请求或花费限制,再重试。
retryable提示不保证原操作没有副作用、重试免费或端点支持幂等。重复 GET 或聊天请求也可能产生费用。- 收到
409时核查原操作,并遵循该端点的幂等规则。规则要求时保留同一键和请求正文;更换键可能创建第二次操作。 - 遇到临时故障,先确认重复执行安全。若有
Retry-After则遵守它,否则使用带抖动且有次数和时间上限的指数退避。不要盲目重放执行结果不明的 Provider 创建操作或计费调用。 - 持续的配置错误需要运维排查,不能依靠无限重试解决。Provider 错误不符合上述示例时,保留原状态和响应。