> For the complete documentation index, see [llms.txt](https://toss-ads.gitbook.io/toss-ads/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://toss-ads.gitbook.io/toss-ads/api-common/response-format.md).

# 응답 형식

토스애즈 API는 요청 결과를 응답 본문의 `resultType`으로 알려줘요. 이 문서에서는 결과에 따라 응답 본문이 어떻게 달라지는지, 각 필드에 어떤 값이 담기는지 알려드려요.

{% hint style="warning" %}
HTTP 상태 코드가 200이어도 `resultType`이 `FAIL`이면 실패예요. 반드시 `resultType`을 확인해 주세요.
{% endhint %}

### 성공 응답

요청에 성공하면 아래와 같은 응답을 받아요. `resultType` 값은 `SUCCESS`이고, `success` 필드에 결과 데이터가 담겨요. `success` 필드에 담기는 데이터의 형식은 API마다 달라요.

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "resultType": "SUCCESS",
  "success": { ... }
}
```

### 실패 응답

요청에 실패하면 아래와 같은 응답을 받아요. `resultType` 값은 `FAIL`이고, `error` 필드에 에러 내용이 담겨요. 이때 `success` 필드의 값은 `null`이에요.

```json
HTTP/1.1 200 OK
Content-Type: application/json

{
  "resultType": "FAIL",
  "success": null,
  "error": {
    "errorType": 0,
    "errorCode": "4095",
    "reason": "허용된 요청량을 초과했습니다. 잠시 후 다시 시도해 주세요.",
    "data": { "origin": "platform", "retryAfterSeconds": 1 },
    "title": null
  }
}
```

Access Token에 문제가 있으면 이 형식이 아니라 짧은 텍스트로 응답해요. 자세한 내용은 [인증 에러](https://toss-ads.gitbook.io/toss-ads/api-common/authentication-errors.md)에서 확인해 주세요.

### 응답 필드

| 필드                | 타입              | 설명                                                                                                                                                  |
| ----------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resultType`      | string          | <p>요청 결과예요.<br>성공하면 <code>SUCCESS</code>, 실패하면 <code>FAIL</code>이에요.</p>                                                                            |
| `success`         | object \| array | <p>결과 데이터예요.<br>형식은 API마다 달라요. 요청에 실패하면 <code>null</code>이에요.</p>                                                                                   |
| `error`           | object          | <p>에러 내용이에요.<br>요청에 실패했을 때만 있어요. 성공 응답에는 이 필드가 없어요.</p>                                                                                             |
| `error.errorCode` | string \| null  | <p>에러 코드예요.<br>API에 따라 <code>"BAD\_REQUEST"</code>처럼 영문으로 된 코드일 수도 있고, <code>"4095"</code>처럼 숫자로 된 코드일 수도 있어요.<br>코드가 없으면 <code>null</code>이에요.</p> |
| `error.reason`    | string          | <p>에러 메시지예요.<br>원인과 해결 방법을 한국어로 알려줘요.</p>                                                                                                           |
| `error.data`      | object          | <p>에러를 처리하는 데 필요한 부가 정보예요.<br>공통 에러에는 <code>origin: "platform"</code>이 들어 있고, 그 밖의 값은 API마다 달라요. 부가 정보가 없으면 빈 객체(<code>{}</code>)로 와요.</p>          |
| `error.errorType` | number          | 에러를 분류하는 번호예요.                                                                                                                                      |
| `error.title`     | string \| null  | 에러 메시지의 제목이에요.                                                                                                                                      |

{% hint style="info" %}
에러 코드별 의미와 해결 방법은 [공통 에러 코드](https://toss-ads.gitbook.io/toss-ads/api-common/error-codes.md)에서 확인해 주세요.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://toss-ads.gitbook.io/toss-ads/api-common/response-format.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
