错误

Developer API 使用常规的 HTTP 状态码，并在每次出错时返回 JSON 响应体。响应体包含：可用于分支判断的稳定 _tag、供您写入日志的 message，以及一行 feedback，说明当错误没有告诉您该如何修改时应向何处反馈：

{
  "_tag": "DeveloperApiForbidden",
  "code": "insufficient_scope",
  "message": "Missing required scope: menus:write",
  "feedback": "If this error does not tell you what to change, or the API is wrong, report it with POST /v1/feedback and cite this response's x-request-id: https://docs.maple.inc/developer-api/concepts/feedback"
}

请根据 _tag（以及存在时的 code）进行分支，不要依赖 message 文本——消息可能变化，标签不会。

状态码

状态	含义	处理方式
400	请求格式错误，或引用了无效的值	修正请求；不要原样重试
401	凭据缺失、格式错误或无法识别，或应用未启用	检查 Authorization 请求头和密钥
403	凭据有效，但不被允许（见下文 code）	调整权限范围或环境
404	资源不存在，或您的凭据看不到它	核对 ID，并确认您已建立连接
409	请求与当前状态冲突	解决冲突（例如该门店已被连接）
422	业务规则或不受支持的功能阻止了该操作	查看 code 和 details；修改请求或门店配置
429	达到了配额或速率限制	等待响应中 retry_after 指定的秒数后再试
5xx	Maple 一侧出现问题	使用指数退避重试

4xx 响应体可以放心写入您自己的日志和仪表板。5xx 响应应使用退避策略重试——订单决定和 webhook 重放端点都是可安全重放的，因此重试不会有副作用。

如果某个错误没有告诉您该如何修改，或者 API 的行为与这些文档所述不符，请发送反馈并引用该请求的 x-request-id。

错误标签

_tag	状态	说明
DeveloperApiBadRequest	400	请求格式错误，或值无效（例如未知的事件类型）。当路径参数、查询参数、请求头或请求体未通过验证时，code 为 invalid_request，消息会指出具体字段和预期内容。对于菜单发布，消息会列出所有验证问题。
DeveloperApiUnauthorized	401	Bearer 凭据缺失、格式错误、已过期，或属于未启用的应用。
DeveloperApiForbidden	403	带有 code:insufficient_scope 或 wrong_environment。
DeveloperApiNotFound	404	资源不存在，或您的凭据看不到它。
DeveloperApiConflict	409	请求与当前状态冲突，例如连接已被其他应用占用的门店。
DeveloperApiInternalError	500	Maple 无法完成该请求。请使用退避策略重试；如果问题持续，请附上 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 重放都是可安全重放的，因此超时后重试不会重复生效。