---
title: "Feedback API"
description: "报告失败的调用、错误或缺失的数据，或者申请我们还没有的 API。免费，有没有 API 密钥都可以；用报告的 id 查看我们的回复。"
---

> Every apinoa docs page as markdown: https://apinoa.com/llms.txt (all in one file: https://apinoa.com/llms-full.txt; this API family in one file: https://apinoa.com/docs/feedback/llms.txt)

```http
POST /v1/feedback
GET  /v1/feedback/{id}
```

当调用失败、返回的值不对、页面上有的内容响应里没有，或者你需要的平台、操作或选项不存在时，请告诉我们。它是免费的，
**不需要 API 密钥**也能发送，所以 AI 代理可以在遇到问题的那一刻就发出。带上你的密钥，报告会关联到你的账户，
我们就能查看你在 `requestId` 中指明的那次调用。

每个报告都有一个 id。它的状态和我们的回复在 `GET /v1/feedback/{id}`。在 `contact` 中提供邮箱地址，或者带上
密钥发送，回复也会通过邮件发给你。

## 发送反馈

```bash tab="cURL"
curl -X POST "https://gateway.apinoa.com/v1/feedback" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "wrong_data",
    "message": "price is the list price, not the sale price shown on the page",
    "platform": "amazon",
    "operation": "product",
    "params": { "asin": "B0CX23V2ZK" },
    "requestId": "43d899616f8e468aa22368bffaae1953",
    "received": "\"price\": { \"amount\": 29.99 }",
    "expected": "24.99",
    "contact": "dev@example.com"
  }'
```

```js tab="JavaScript"
const res = await fetch("https://gateway.apinoa.com/v1/feedback", {
  method: "POST",
  // 加上 "x-api-key" 可将报告关联到你的账户。
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    type: "feature_request",
    message: "希望提供 Etsy 的商品和评论，字段与 Shopify 商品相同。",
    contact: "dev@example.com",
  }),
});
const { data } = await res.json(); // { id, status, createdAt }
```

```python tab="Python"
import os

import requests

res = requests.post(
    "https://gateway.apinoa.com/v1/feedback",
    headers={"x-api-key": os.environ["APINOA_API_KEY"]},
    json={
        "type": "error",
        "message": "tiktok posts 带 hashtag 从今天早上起每次都返回 502",
        "platform": "tiktok",
        "operation": "posts",
        "params": {"hashtag": "glassskin"},
        "requestId": "43d899616f8e468aa22368bffaae1953",
    },
    timeout=30,
)
body = res.json()
```

## 参数

**请求头**

| 请求头 | 必填 | 说明 |
|---|---|---|
| `Content-Type` | | `application/json`。 |
| `x-api-key` | | 你的 API 密钥，用于将报告关联到你的账户。省略则匿名发送；如果发送了密钥，它必须有效。 |

**请求体**：最大 64 KB 的 JSON 对象。

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `type` | string | 是 | 下列类型之一。 |
| `message` | string | 是 | 用你自己的话说明发生了什么，或你需要什么。最多 4,000 个字符。 |
| `platform` | string | | 路径中的平台名：`amazon`、`tiktok`、`google`… |
| `operation` | string | | 路径中的操作名：`search`、`product`、`posts`… |
| `params` | object | | 你发送的参数。最大 8 KB。 |
| `requestId` | string | | 你要报告的那个响应的 `requestId`。与密钥一起发送时，我们可以查看那次调用。 |
| `url` | string | | 显示正确数据的页面，或报告所涉及的条目。 |
| `received` | any | | 响应中有误的部分：文本，或原样的 JSON 值。最大 16 KB。 |
| `expected` | any | | 本应得到的内容：文本或 JSON 值。最多 4,000 个字符。 |
| `contact` | string | | 接收我们回复的邮箱地址。 |
| `source` | string | | 发送方，例如你的代理或应用的名称。最多 32 个字符。 |

| `type` | 适用情况 | 请附上 |
|---|---|---|
| `error` | 调用失败或行为异常。 | `platform`、`operation`、`params`、`requestId`，以及收到的错误（放在 `received`）。 |
| `wrong_data` | 某个字段的值不对。 | 同上，再加上 `expected`，或显示正确值的 `url`。 |
| `missing_data` | 页面上显示的内容不在响应里。 | 同上，以及该页面的 `url`。 |
| `feature_request` | 你需要我们还没有的平台、操作、字段或选项。 | 在 `message` 中说明你想怎么调用、想得到什么。 |
| `other` | 其他任何情况。 | |

## 响应

新报告返回 `201 Created`：

```json
{
  "success": true,
  "data": {
    "id": "fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b",
    "status": "received",
    "createdAt": "2026-11-11T10:00:00Z"
  }
}
```

一天之内用同一个密钥（没有密钥时，来自同一发送方）再次发送相同的 `type` 和 `message`，不会新建报告，而是以
`200 OK` 返回第一个报告。

## 查看状态和回复

```bash
curl "https://gateway.apinoa.com/v1/feedback/fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b"
```

不需要密钥，有 id 即可。不会返回你发送的内容，只返回我们这一侧的状态和回复：

```json
{
  "success": true,
  "data": {
    "id": "fb_6f1c2a9e0b4d4e7f8a3b5c1d2e9f0a7b",
    "type": "wrong_data",
    "status": "resolved",
    "reply": "Fixed: product now returns the sale price. Retry the call.",
    "repliedAt": "2026-11-12T08:30:00Z",
    "createdAt": "2026-11-11T10:00:00Z",
    "updatedAt": "2026-11-12T08:30:00Z"
  }
}
```

| 字段 | 类型 | 含义 |
|---|---|---|
| `status` | string | `received`，处理中为 `in_progress`，之后为 `resolved` 或 `declined`。 |
| `reply` | string \| null | 我们的回复；回复之前为 `null`。 |
| `repliedAt` | string \| null | 回复的时间。 |
| `createdAt`, `updatedAt` | string | 报告到达的时间和最后一次变更的时间。 |

## SDK 和 MCP

- **TypeScript**：`client.feedback.send({ type, message, ... })` 和 `client.feedback.get({ id })`。要不带密钥
  发送，请用 `new ApinoaClient({ auth: false })` 创建客户端。
- **Python**：`client.feedback.send(type=..., message=..., request_id=...)` 和 `client.feedback.get(id)`。
- **MCP**：`send_feedback` 和 `get_feedback` 工具。不需要密钥。

## 错误

| 状态 | 代码 | 含义 |
|---|---|---|
| 400 | `BAD_REQUEST` | 请求体不是带有 `type` 和 `message` 的 JSON 对象，或某个字段无效；错误信息会指出是哪个字段。 |
| 401 | `UNAUTHORIZED` | 发送了 `x-api-key`，但密钥无效或已撤销。要不带密钥发送，请去掉该请求头。 |
| 404 | `NOT_FOUND` | 没有此 id 的反馈。 |
| 413 | `PAYLOAD_TOO_LARGE` | 请求体超过 64 KB。 |
| 429 | `RATE_LIMITED` | 同一发送方的报告太多。请等待 `Retry-After` 秒。 |
| 503 | `SERVICE_UNAVAILABLE` | 暂时无法保存报告，请稍后重试。 |

## 限制和价格

- **免费。** 无论是否带密钥，反馈都不计费。
- **频率。** 不带密钥时，同一发送方每小时 10 个、每天 50 个；带密钥时，每个密钥每小时 30 个。不带密钥时，
  在繁忙时段可能更早收到 `429`；带密钥发送的报告不受影响。
- **我们保留的内容。** 报告以及你提供的邮箱地址会被保留，以便我们回复并修复你报告的问题。参见
  [隐私政策](/privacy)。
