调用约定

请求

使用 HTTPS 和 JSON。带请求体的请求必须设置 Content-Type: application/json，请求体是一个 JSON 对象。
未定义的字段会被拒绝（400 COMMON.INVALID_INPUT），这样拼错的字段名不会被静默忽略。
请求体最大 64 KiB。
服务为每个响应生成 X-Request-ID，客户端传入的值会被忽略。排查问题时请提供这个 ID。
所有 /v1 响应都带 Cache-Control: no-store。

返回信封

成功：

{ "code": 0, "message": "success", "data": { "execution": { }, "result": { } } }

失败：

{
  "code": 409,
  "error_code": "EXECUTION.DUPLICATE_INVOCATION",
  "message": "This invocation was already executed.",
  "request_id": "req_5f0c...",
  "execution": { }
}

请以 error_code 作为分支判断依据。message 是固定的安全文本，不包含数据源的原始返回、URL 或内部错误。完整列表见错误码。

invocation_id 与执行记录

每个调用能力的请求都必须携带调用方生成的 invocation_id（1–128 个字符，A-Z a-z 0-9 . _ : -）。服务按（调用方，invocation_id，操作）记录一条执行记录，并且在调用数据源之前写入：

记录写不进去时，不调用数据源，返回 503 SERVICES.RECORD_UNAVAILABLE；
同一调用方用同一个 invocation_id 再次调用同一操作时，不会再调用数据源，返回 409 EXECUTION.DUPLICATE_INVOCATION 并附上已有的 execution。服务不保存结果，因此无法重放上一次的结果。

在执行记录产生之前就被拒绝的请求（鉴权、权限、参数校验、未知或停用的数据源、本地并发限制、请求体过大）不带 execution，也没有启动任何数据源调用。

execution 字段

{
  "id": "exe_0192f6...",
  "invocation_id": "order-10086-1",
  "capability": "public_holiday",
  "operation": "public_holiday.query",
  "provider": "holiday-cn",
  "outcome": "succeeded",
  "error_category": null,
  "error_code": null,
  "usage": { "provider_requests": 0, "units": [{ "name": "days", "value": 8, "source": "measured" }] },
  "request_id": "req_5f0c...",
  "started_at": "2026-10-11T09:00:00Z",
  "finished_at": "2026-10-11T09:00:01Z"
}

结果状态 outcome

outcome	含义	调用方处理
`succeeded`	已返回结果	按产品规则计费
`failed`	确定没有可用结果	按失败规则处理
`unknown`	数据源已收到请求，但结果无法确定	不要自动重试，通过调用日志对账
`accepted`	异步任务已创建，尚未结束	稍后查询
`expired`	数据源报告异步结果已过期	按失败规则处理
`in_progress`	仅出现在对账中：仍在截止时间内	稍后再查

超过截止时间仍未结束的执行（例如进程崩溃）会被报告为 unknown。

用量 usage

provider_requests：实际发往数据源的请求次数。本地数据（如 holiday-cn）为 0。
units[]：能力自己的计量单位，例如节假日的 days、学术检索的 works。source 为 provider（数据源上报）或 measured（服务统计）。拿不到的数量会省略，不会估算。
用量中不包含金额，价格由调用方决定。

重试规则

情况	能否重试	用哪个 invocation_id
没有 `execution` 的错误：`429 COMMON.RATE_LIMITED`、`503 SERVICES.RECORD_UNAVAILABLE`、`503 SERVICES.PROVIDER_DISABLED`	可以，稍后重试	原 ID
参数错误：`400`、`413`、`415`、`422 COMMON.VALIDATION_FAILED`	修正请求后再调用	原 ID
`outcome` 为 `failed`，例如 `PROVIDER.UNAVAILABLE`、`PROVIDER.RATE_LIMITED`、`COMMON.TIMEOUT`	可以，按 `Retry-After` 退避	新 ID（原 ID 会返回 409）
`outcome` 为 `unknown`（`502 EXECUTION.OUTCOME_UNKNOWN`）	不要自动重试	先在调用日志中对账，再人工决定
`409 EXECUTION.DUPLICATE_INVOCATION`	不需要	读取附带的 `execution` 了解第一次的结果

超时

数据源的默认超时为 30 秒，个别数据源更长（例如 world-bank 为 60 秒，见能力参考中的 timeout_seconds）。客户端的读取超时建议设为 90 秒以上，避免在服务完成执行记录之前主动断开。

健康检查

接口	鉴权	说明
`GET /health/live`	不需要	进程存活
`GET /health/ready`	不需要	配置和数据库可用；不会调用任何付费数据源