---
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)을 참고하세요.
