同步规则与错误处理

保持更新顺序

车辆和 Rental upsert 以组织和 external_id 为边界。首次创建时应发送已有上下文；后续发生内容变化时，发送 source_revision 或 source_updated_at。建议使用源系统中的整数版本号并严格递增。一旦保存了版本号，时间戳不能取代它。省略的属性保留现值；显式 null 只能清空允许为空的字段；未知属性会被拒绝。

Rental 生命周期规则仍然适用：第一次检查开始后，车辆分配会锁定；交车后，部分计划字段会锁定；业务完成后，只能进行受支持的报告更正。冲突或更旧的更新会收到结构化错误。请先读取当前资源，再使用新版本重试。

让 POST 命令可以安全重试

每个写入 POST 都要求 Idempotency-Key。每项预期操作生成一个唯一值，网络重试时保持不变，且绝不能把同一值用于不同请求体。该键以组织为边界并保留七天。重放同一个已完成命令会返回原始成功响应；冲突复用则失败。

按外部 ID 的 PUT 具有确定性，但内容变化时仍需要版本标记。不要为同一车辆或预订的重试创建新的外部 ID。

处理错误

API 错误使用 application/problem+json，包含稳定的 code、HTTP status、可读的 detail、request_id、retryable 和可选字段错误 errors。联系支持时请记录 request_id，但不要记录密钥或私有文档内容。

type URL 指向公开错误说明。例如，INVALID_API_KEY会解释原因与下一步。中间件返回的每个错误代码在所有支持语言中都有对应页面。

响应	应对方式
401	检查密钥是否有效、已过期或已撤销。
403	检查密钥权限和组织的商业访问资格。
409	修改请求前先读取当前资源或检查幂等冲突。
422	更正指定字段；不要原样重试无效请求体。
429	遵守 Retry-After 和限流响应头。
503	根据 retryable 和可能存在的 Retry-After 重试。

GET /v1/capabilities 返回密钥当前有效的配额、文件限制和保留期限。每个路由可能返回的响应以 API 参考为准。