> 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/error-codes.md).

# 공통 에러 코드

공통 에러는 토스애즈 API의 모든 API에서 발생할 수 있는 에러예요. 이 문서에서는 공통 에러 코드별 원인과 해결 방법을 알려드려요. 각 API에서만 발생하는 에러는 해당 API 문서에서 확인해 주세요.

### 공통 에러 구분하기

공통 에러 응답에는 `error` 필드 안의 `data`에 항상 `"origin": "platform"`이 들어 있어요. 이 값이 있으면 공통 에러예요. 응답 구조는 [응답 형식](https://toss-ads.gitbook.io/toss-ads/api-common/response-format.md)과 같아요.

```json
{
  "resultType": "FAIL",
  "success": null,
  "error": {
    "errorType": 0,
    "errorCode": "4104",
    "reason": "폐기된 클라이언트입니다. 키 재발급이 필요합니다.",
    "data": { "origin": "platform" },
    "title": null
  }
}
```

{% hint style="info" %}
에러 코드(`errorCode`)가 아래 표의 코드와 같더라도 `error` 필드의 `data` 안에 `"origin": "platform"`이 없으면 공통 에러가 아니에요. 공통 에러가 아닌 경우 코드가 같더라도 API마다 의미가 다를 수 있으니 해당 API 문서를 확인해 주세요.
{% endhint %}

### 에러 코드 목록

| errorCode | HTTP 상태 코드 | 원인                                                                                                                   | 해결 방법                                                                        | 재시도    |
| --------- | ---------- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------ |
| `4040`    | 404        | <p>존재하지 않는 경로로 호출했거나 HTTP 메서드가 틀렸어요.<br>reason: <code>등록되지 않은 API 경로 또는 메서드입니다.</code></p>                           | API 문서에서 경로와 메서드를 확인해 주세요.                                                   | X      |
| `4095`    | 200        | <p>API 키 하나로 1초에 50건이 넘게 호출했어요.<br>reason: <code>허용된 요청량을 초과했습니다. 잠시 후 다시 시도해 주세요.</code></p>                        | `error.data.retryAfterSeconds`에 담긴 시간(초)만큼 기다린 뒤 다시 호출해 주세요. 호출량도 줄여 주세요.    | O      |
| `4102`    | 200        | <p>광고주센터에서 발급하지 않은 API 키로 호출했어요.<br>reason: <code>등록되지 않은 클라이언트입니다.</code></p>                                       | 광고주센터 > 광고도구 > API 키에서 발급받은 키를 사용해 주세요.                                      | X      |
| `4103`    | 200        | <p>API 키가 일시적으로 차단됐어요.<br>reason: <code>일시 차단된 클라이언트입니다. 고객센터에 문의해 주세요.</code></p>                                   | [채널톡](https://toss-business.channel.io/)으로 문의해 주세요. 차단이 해제되면 다시 호출할 수 있어요.   | 해제 후 O |
| `4104`    | 200        | <p>API 키가 폐기됐어요.<br>reason: <code>폐기된 클라이언트입니다. 키 재발급이 필요합니다.</code></p>                                             | 광고주센터 > 광고도구 > API 키에서 키를 새로 발급받아 주세요.                                       | X      |
| `4200`    | 200        | <p>API 키에 이 API를 호출할 권한(scope)이 없어요.<br>reason: <code>이 API를 호출할 scope 권한이 없는 키입니다. 키의 허용 scope를 확인해 주세요.</code></p> | Access Token을 발급받을 때 `scope`에 이 API에 필요한 권한을 넣었는지 확인해 주세요.                   | X      |
| `5000`    | 500        | <p>서버에 일시적인 문제가 생겼어요.<br>reason: <code>일시적인 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.</code></p>                                  | 잠시 후 다시 호출해 주세요. 계속 발생하면 [채널톡](https://toss-business.channel.io/)으로 문의해 주세요. | O      |

### 재시도 방법

재시도 열이 X인 에러는 다시 호출해도 결과가 같아요. 원인을 해결한 뒤 호출해 주세요.

* `4095`는 `error.data.retryAfterSeconds`만큼 기다린 뒤 다시 호출해 주세요.
* `4103`은 차단이 해제된 뒤 다시 호출해 주세요.
* `5000`은 다시 시도할 때마다 기다리는 시간을 2배씩 늘리는 걸 권장해요(지수 백오프). 예: 1초, 2초, 4초, 8초 간격으로 재시도.


---

# 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/error-codes.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.
