> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误

> 使用标准 HTTP 状态码，并返回包含稳定的机器可读标签和人类可读消息的 JSON 响应体。

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

```json theme={null}
{
  "_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` 响应应使用退避策略重试——[订单决定](/zh/developer-api/guides/receive-orders)和 webhook 重放端点都是可安全重放的，因此重试不会有副作用。

如果某个错误没有告诉您该如何修改，或者 API 的行为与这些文档所述不符，请[发送反馈](/zh/developer-api/concepts/feedback)并引用该请求的 `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。当提供方的结果不确定时，切勿换用新的键来绕过。请参阅[接受预订](/zh/developer-api/guides/take-bookings)。

`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` — 凭据有效，但缺少端点所需的权限范围。请对照[权限范围表](/zh/developer-api/concepts/authentication)检查 `GET /v1/me` 的结果。
* `wrong_environment` — 您用测试凭据访问了正式数据，或反之。凭据的前缀决定了它所属的环境。

## 妥善处理错误

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.