> For the complete documentation index, see [llms.txt](https://help.citrusad.com/retail-media-interface/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.citrusad.com/retail-media-interface/partner/ko/partner-api-overview/error-handling.md).

# 오류 처리

Epsilon Retail Media 파트너 API는 구조화되고 일관된 오류 처리 방식을 따릅니다. 이를 통해 오류 응답을 예측할 수 있고, 구문 분석이 용이하며, 디버깅에 유용하도록 합니다.

## 오류 응답 구조

오류가 발생하면 API는 다음을 반환합니다.

* 표준 HTTP 상태 코드.
* code, message 및 선택적 details 필드가 포함된 구조화된 JSON 본문.
* 클라이언트가 여러 문제를 한 번에 해결할 수 있도록 하는 필드 수준의 위반 사항 목록(해당하는 경우).

## 오류 처리를 위한 기본 전략

오류가 발생하면 다음 단계를 따르세요.

1. **오류 메시지를 주의 깊게 읽으세요** - 오류 응답은 무엇이 잘못되었는지, 어떤 필드로 인해 문제가 발생했는지에 대한 특정 정보를 제공합니다.
2. **엔드포인트 페이지를 검토하세요** - 진행 방법을 잘 모르겠다면 사용 중인 엔드포인트의 특정 페이지를 검토하세요.
3. **지원팀에 문의하세요** - 문제가 계속 발생하면 지원 포털에서 케이스를 열 수 있습니다. 다음 정보를 제공해 주세요.
   * 요청 중인 정확한 API 호출.
   * 특정 리테일러 및 팀.
   * 생성/업데이트 중인 특정 엔티티.
   * 표시되는 전체 오류 응답.

이 정보는 저희 팀이 귀하를 효율적이고 효과적으로 도울 수 있도록 합니다.

### 단일 위반 예시

```json
{
  "code": 3,
  "message": "Invalid argument(s) for product campaign creation",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "maxBid",
          "description": "[maxBid] must be greater or equal [minBid]"
        }
      ]
    }
  ]
}
```

### 다중 위반 예시

```json
{
  "code": 3,
  "message": "Invalid argument(s) for product campaign update",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.BadRequest",
      "fieldViolations": [
        {
          "field": "strategy.fixedTenancy.catalogCosts",
          "description": "all catalog cost percentages for fixed tenancy must sum to 100%"
        },
        {
          "field": "strategy.fixedTenancy.catalogCosts",
          "description": "fixed tenancy catalog cost [...] is duplicated in the list"
        }
      ]
    }
  ]
}
```

## 표준 HTTP 상태 코드

| HTTP 상태 코드                | 의미               | 발생 시점                   |
| ------------------------- | ---------------- | ----------------------- |
| 200 OK                    | 요청 성공            | 성공적인 API 호출             |
| 204 No Content            | 성공, 응답 본문 없음     | 반환 페이로드가 없는 성공적인 요청     |
| 400 Bad Request           | 유효하지 않은 입력       | 잘못된 형식의 요청 또는 유효성 검사 실패 |
| 401 Unauthorized          | 토큰 누락 또는 유효하지 않음 | 토큰이 제공되지 않았거나 만료됨       |
| 403 Forbidden             | 접근 거부됨           | 토큰이 유효하지만 권한이 부족함       |
| 404 Not Found             | 리소스를 찾을 수 없음     | 유효하지 않은 엔드포인트 또는 리소스 ID |
| 409 Conflict              | 중복되거나 충돌하는 데이터   | 리소가 이미 존재하거나 제약 조건을 위반함 |
| 429 Too Many Requests     | 요청 제한 초과         | 단시간 내에 너무 많은 요청 발생      |
| 500 Internal Server Error | 서버 측 문제          | 서버의 예기치 않은 오류           |
| 503 Service Unavailable   | 일시적 장애           | 서비스가 중단되었거나 유지보수 중임     |

## gRPC-HTTP 오류 코드 매핑

| gRPC 코드 | gRPC 이름              | HTTP 코드 | HTTP 이름               |
| ------- | -------------------- | ------- | --------------------- |
| 0       | OK                   | 200     | OK                    |
| 1       | CANCELLED            | 499     | Client Closed Request |
| 2       | UNKNOWN              | 500     | Internal Server Error |
| 3       | INVALID\_ARGUMENT    | 400     | Bad Request           |
| 4       | DEADLINE\_EXCEEDED   | 504     | 게이트웨이 시간 초과           |
| 5       | NOT\_FOUND           | 404     | 찾을 수 없음               |
| 6       | ALREADY\_EXISTS      | 409     | 충돌                    |
| 7       | PERMISSION\_DENIED   | 403     | 금지됨                   |
| 8       | RESOURCE\_EXHAUSTED  | 429     | 너무 많은 요청              |
| 9       | FAILED\_PRECONDITION | 400     | Bad Request           |
| 10      | ABORTED              | 409     | 충돌                    |
| 11      | OUT\_OF\_RANGE       | 400     | Bad Request           |
| 12      | UNIMPLEMENTED        | 501     | 구현되지 않음               |
| 13      | INTERNAL             | 500     | Internal Server Error |
| 14      | UNAVAILABLE          | 503     | 서비스를 사용할 수 없음         |
| 15      | DATA\_LOSS           | 500     | Internal Server Error |
| 16      | UNAUTHENTICATED      | 401     | 권한 없음                 |


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.citrusad.com/retail-media-interface/partner/ko/partner-api-overview/error-handling.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.