约定
ID、时间戳、错误格式、版本控制和重试。
| 约定 | 规则 |
|---|---|
| ID | UUID，视为不透明。完整存储；绝不要解析或截短其中任何一个 |
| 时间戳 | UTC 中的 RFC 3339，例如 2026-09-22T04:10:00Z |
| 未知字段 | 忽略它们。新的响应字段和新的状态值可能会在不提升版本号的情况下出现 |
| 版本控制 | 前缀包含主版本号。破坏性变更会获得新的前缀并提前通知 |
| 错误 | {"description": "…", "error": {"error_code": "…", "error_attributes": {…}}} — 根据 error.error_code，记录 描述，切勿根据其文本进行匹配。参见 错误与限制 |
| 重试 | 遵守 Retry-After 在 429 时。在 5xx 时，使用指数退避和抖动重试 |
幂等性
发送一个 idempotency_key 在你启动的每次运行中都使用它。它是你自己的字符串——一个集数、一个作业 ID，或者任何对该工作单元保持稳定的值。
- 相同的键与 相同的主体 会返回已存在的运行，而不是启动第二个。
- 相同的键与一个 不同的主体 会被拒绝，并返回
idempotency_conflict。新工作请使用新的键。
这使得超时后的重试是安全的，这就是一次运行与一个会向你计费的重复运行之间的区别。
跟踪
每个响应都包含 x-morphic-trace-id。请记录它。当你报告问题时，正是这个 ID 让我们能在几秒内找到该运行，而不是向你索要一个时间范围。