Skip to main content
Developer API 使用常规的 HTTP 状态码，并在每次出错时返回 JSON 响应体。响应体包含：可用于分支判断的稳定 _tag、供您写入日志的 message，以及一行 feedback，说明当错误没有告诉您该如何修改时应向何处反馈：
请根据 _tag（以及存在时的 code）进行分支，不要依赖 message 文本——消息可能变化，标签不会。

​
状态码

4xx 响应体可以放心写入您自己的日志和仪表板。5xx 响应应使用退避策略重试——订单决定和 webhook 重放端点都是可安全重放的，因此重试不会有副作用。 如果某个错误没有告诉您该如何修改，或者 API 的行为与这些文档所述不符，请发送反馈并引用该请求的 x-request-id。

​
错误标签

DeveloperApiUnprocessable 是带有 code、message 和可选 details 的 422。DeveloperApiRateLimited 是 429，带有以秒为单位的 retry_after，以及对应的 Retry-After HTTP 响应头。

​
预订错误码

预订变更请求的请求体会拒绝未知字段并返回 400，包括拼错的可选字段，例如写成 expectedVersion 而不是 expected_version。幂等键必须包含 1–255 个字符。
  • 400:invalid_slot_token、expired_slot_token、invalid_window、invalid_cursor、invalid_phone、location_required、change_required、invalid_blackout_dates；配置模式（schema）验证失败时会包含验证路径。
  • 409:stale_version（details.expected/actual）、stale_blackout_dates、stale_configuration、idempotency_key_reused、overlapping_booking、slot_unavailable、hold_expired、hold_consumed、not_changeable、not_cancellable、illegal_transition（details.from_status）、waitlist_closed、operation_in_progress（details.operation_id、details.retry_after、details.reason）。
  • 422:bookings_not_enabled、party_size_out_of_bounds、outside_booking_window、large_party_inquiry_required、date_blocked、capability_unsupported、guest_contact_required、guest_messaging_unavailable、payment_instrument_required、configuration_missing、configuration_rejected、provider_rejected。
对于 operation_in_progress，请使用原来的键重试原始请求。如果 details.reason 为 replay_window_expired，请停止自动重试，并携带操作 ID 联系 Maple。当提供方的结果不确定时，切勿换用新的键来绕过。请参阅接受预订。 provider_rejected 是最终结果：提供方拒绝了该请求，且没有任何变化。例如，OpenTable 可能不允许通过 Maple 修改或取消某个预订；但餐厅方仍可修改。重试只会得到同样的答案。 当提供方说明了拒绝原因时，您收到的是 Maple 原生门店在相同情况下返回的错误码，而不是 provider_rejected:
  • 时间太近，无法预订或改到该时间：422 outside_booking_window，并带有 details.reason: inside_min_lead;
  • 预订已经开始或即将开始：409 not_changeable 或 409 not_cancellable，并带有 details.reason: outside_policy_window;
  • 该时间需要提供方无法通过 Maple 收取的银行卡：422 payment_instrument_required。
这些同样是最终结果，且没有任何变化。

​
403 错误码

DeveloperApiForbidden 总会告诉您_原因_:
  • insufficient_scope — 凭据有效，但缺少端点所需的权限范围。请对照权限范围表检查 GET /v1/me 的结果。
  • wrong_environment — 您用测试凭据访问了正式数据，或反之。凭据的前缀决定了它所属的环境。

​
妥善处理错误

  • 根据 _tag/code 分支，记录 message。 标签是您的控制流；消息是给人调试用的。
  • 不要原样重试 4xx。 它们意味着请求需要修改。唯一的例外：409 可能在冲突状态解决后自行消除。
  • 使用指数退避重试 5xx。 加入抖动（jitter）以避免重试风暴。
  • 写入类请求的重试是安全的。 订单决定和 webhook 重放都是可安全重放的，因此超时后重试不会重复生效。