> ## 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.

# 反馈

> 向 Maple 反馈漏洞、缺失的功能、错误的文档，或您无法据以处理的错误。

当 API 出现错误、无法满足您的需求、与这些文档不一致，或返回的错误没有告诉您该如何修改时，请发送 `POST /v1/feedback`。它既是为人设计的，也是为承担了此 API 大部分工作的编码助手设计的，这样遇到障碍的助手可以在同一次会话中直接报告，而不是绕过去。

```bash theme={null}
curl https://api.maple.inc/v1/feedback \
  -H "Authorization: Bearer $MAPLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "unclear_error",
    "summary": "Waitlist join answers 400 without naming the field",
    "attempted": "Add a party of four to the waitlist",
    "expected": "The error names the field that failed",
    "endpoint": "POST /v1/waitlist_entries",
    "request_ids": ["req_3f2b7c1e-9a4d-4e8b-b1c2-5d6e7f8a9b0c"]
  }'
```

| 字段 | 是否必填 | 填写内容 |
| - | - | - |
| `kind` | 是 | `bug`、`missing_capability`、`docs_wrong`、`unclear_error` 或 `other` |
| `summary` | 是 | 一行文字，最多 200 个字符 |
| `attempted` | 否 | 您当时想做什么，描述目标而不是某次调用；如果反馈与具体任务无关，可以省略 |
| `expected` | 否 | 您期望 API 做什么 |
| `observed` | 否 | 它实际做了什么 |
| `endpoint` | 否 | 方法和路径，例如 `POST /v1/waitlist_entries` |
| `request_ids` | 否 | 相关请求的 ID，最多十个，通常是它们的 `x-request-id` 值 |

## 引用您的请求

每个响应都带有 `x-request-id` 响应头。请把相关请求的 ID 放进 `request_ids`，因为它们能让我们看到您实际发送的请求的操作、状态和错误码。您发送反馈时，我们会把这些详情复制到反馈上，所以即使请求历史在七天后过期，这些信息仍然可读。如果某个 ID 无法与您应用在同一环境、最近七天内的请求匹配（例如来自其他系统的 ID），则会按您发送的原样保留；报告绝不会因为某个 ID 而被拒绝。

## 不会破坏的契约

编码助手可能从只编写一次、然后运行多年的代码中发送反馈，因此我们绝不会对 `POST /v1/feedback` 做出破坏性变更。我们可能会添加可选字段和新的 `kind` 值，响应也可能新增字段，所以请忽略您不认识的字段。我们不会删除或重命名字段、更改字段含义、将可选字段改为必填、添加必填字段、移除某个 `kind`，也不会收紧长度限制。今天能用的请求会一直有效。

## 接下来会怎样

API 会保存该报告，并返回 `200`，其中包含一个 `status` 为 `received` 的 `feedback` 对象。Maple 每周都会阅读反馈并决定要修改什么；发送反馈本身不会改变任何东西，API 也不会回复。请不要在文本中包含机密信息、API 密钥和顾客信息。

任何凭据都可以在任一环境中发送反馈，无需任何权限范围。每个应用在每个环境中每小时最多可发送 20 份报告；超出后 API 会返回 `429`，并带有 `Retry-After` 响应头。


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