> For the complete documentation index, see [llms.txt](https://toss-ads.gitbook.io/guide/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/guide/catalog/troubleshooting.md).

# 카탈로그 문제 해결하기

카탈로그를 연동하고 광고를 운영하다 보면 여러 문제가 생길 수 있어요. 어떤 증상에 해당하는지 확인하고, 해당 섹션의 순서를 따라 해결해 주세요.

* 상품이 등록되지 않을 때
* 상품이 광고에 노출되지 않을 때
* 성과가 측정되지 않을 때

카탈로그를 만들고 상품을 관리하는 방법은 [카탈로그 연동 가이드](/guide/catalog/how-to.md)를 참고해 주세요.

## 상품이 등록되지 않을 때

등록 결과는 **업데이트 관리** 탭에서 확인해요. 등록되지 않은 상품이 있으면 **문제 보고서**가 발행돼요. 등록에 성공했더라도 노출 불가 문제나 권장 조치가 있는 상품이 있으면 문제 보고서가 발행될 수 있어요. 문제 보고서를 내려받으면 상품별 원인을 확인할 수 있어요.

<figure><img src="/files/oYiJZu4QpfFjVVjCKlfS" alt=""><figcaption></figcaption></figure>

### 모든 상품이 등록되지 않았다면

1. 자동 등록이라면 상품 목록 URL이 `https://`로 시작하고 누구나 접근할 수 있는지 확인해 주세요. URL에 연결된 상품 데이터 파일은 CSV 또는 TSV 형식이어야 하며, XML 등 다른 형식은 지원하지 않아요.
2. 수동 등록이라면 파일이 CSV 또는 TSV 형식이고 100MB 이하인지 확인해 주세요.
3. 첫 행에 필수 상품 정보 6가지인 `id`, `title`, `brand`, `image_url`, `landing_url`, `price` 열이 모두 있는지 확인해 주세요.
4. 상품이 1건 이상 있고, 자동 등록은 500만 건, 수동 등록은 10만 건을 넘지 않는지 확인해 주세요.
5. 원본을 수정한 뒤 등록 방식에 맞게 다시 등록해 주세요.
   * 자동 등록은 즉시 업데이트해 주세요.
   * 수동 등록은 수정한 파일을 다시 등록해 주세요.

### 일부 상품만 등록되지 않았다면

1. 문제 보고서를 내려받아 노출 불가 사유 탭의 `문제` 항목에서 상품별 원인을 확인해 주세요. 필수 상품 정보인 `id`, `title`, `brand`, `image_url`, `landing_url`, `price`가 비어 있는 상품은 등록되지 않고 문제 보고서에서만 확인할 수 있어요. 이미지, URL, 가격, 재고 상태, 허용값, 추적 URL 등의 문제로 일부 상품이 등록되지 않을 수도 있어요.
2. 같은 문제가 여러 상품에 반복되는지 확인하고, 원본 상품 목록에서 잘못된 값을 수정해 주세요.
3. 자동 등록은 즉시 업데이트하고, 수동 등록은 수정한 파일을 다시 등록해 주세요.
4. 수정한 상품이 **노출 가능** 상태로 바뀌었는지 확인해 주세요.

### 자동 업데이트가 실패했다면

<figure><img src="/files/nlUyM956pQUWlgZRk29I" alt=""><figcaption></figcaption></figure>

정기 업데이트가 실패하면 마지막으로 등록에 성공한 상품 목록을 계속 광고에 사용해요. 기존 광고가 바로 중단되지는 않지만, 실패한 업데이트에 담긴 가격, 재고, 신규 상품 변경은 반영되지 않아요.

1. **업데이트 관리** 탭에서 마지막 실패 시각을 확인하고, **문제 보기** 버튼을 눌러 실패 원인을 확인해 주세요.
2. 연결 상태가 **연결 오류**라면 상품 목록 URL에 누구나 접근할 수 있는지 확인해 주세요. 연결 상태의 의미는 [카탈로그 연동 가이드의 연결 상태 확인하기](/guide/catalog/how-to.md)에서 확인할 수 있어요.
3. 원본을 수정한 뒤 **업데이트** 버튼으로 즉시 업데이트해 주세요. 즉시 업데이트는 3시간에 한 번만 할 수 있어요.
4. 업데이트에 성공하면 **상품** 탭에서 가격과 재고가 최신 값인지 확인해 주세요.

## 상품이 광고에 노출되지 않을 때

<figure><img src="/files/rWZTPQjKjULLu58Yg4PL" alt=""><figcaption></figcaption></figure>

광고에 나가는 상품은 **노출 가능** 상태이면서 **광고 사용 여부**가 **사용**인 상품이에요. 등록은 됐지만 광고에 나가지 않는 상품은 다음 순서로 확인해 주세요.

1. 상품 탭에서 **광고 사용 여부**를 확인해 주세요. 미사용 상품은 광고에 나가지 않아요. 다시 광고하려면 **사용**으로 바꿔 주세요.
2. 상태가 **노출 불가**라면 상품을 선택하고 상품 상세에서 사유를 확인해 주세요.
3. 상품 정보 문제라면 아래 표에서 해결 방법을 확인하고 원본을 수정해 주세요.
4. 자동 등록은 다음 예약 업데이트나 즉시 업데이트를 진행하고, 수동 등록은 수정한 파일을 다시 등록해 주세요.
5. 등록이 끝나면 다시 검토된 상품 상태를 확인해 주세요. 상품 정보 문제가 없는데도 노출되지 않는다면 심사 반려 사유를 확인해 주세요.

원본만 수정해도 상품 상태가 바로 바뀌지는 않아요. 자동 등록은 다음 예약 업데이트나 즉시 업데이트, 수동 등록은 수정한 파일 등록이 끝난 뒤 다시 검토돼요.

### 문제별 해결 방법

노출 불가 문제는 1건이라도 있으면 해당 상품이 광고에 노출되지 않아요. 권장 조치는 당장 노출을 막지는 않지만, 해당 상품 정보가 광고에 반영되지 않거나 노출과 성과에 영향을 줄 수 있어요. 각 상품 정보의 형식과 제한은 [카탈로그 연동 스펙](/guide/catalog/spec.md)을 참고해 주세요.

### **노출 불가**

| 문제               | 설명                                                          | 해결 방법                                                                                     | 대상 상품 정보                                                    |
| ---------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| 재고 없음            | 재고가 없는 상품이에요                                                | `in stock` 또는 `available for order`일 때만 노출돼요. 다시 판매하려면 원본의 재고 값을 바꾸고 업데이트해 주세요            | `availability`                                              |
| 필수 상품 정보 누락      | 1개 이상의 필수 상품 정보가 비어 있어요                                     | 비어 있는 필수 상품 정보를 모두 채운 뒤, 상품 목록 URL 또는 파일을 다시 올려주세요.                                       | `id`, `title`, `brand`, `image_url`, `landing_url`, `price` |
| 글자 수 미달 및 초과     | 필수 상품 정보의 글자 수가 허용 범위를 벗어났어요                                | [카탈로그 연동 스펙의 글자 수 제한](/guide/catalog/spec.md)에 맞게 수정해 주세요                                 | `id`, `title`, `brand`, `image_url`, `landing_url`          |
| URL 형식 오류        | URL이 `https://`로 시작하지 않아요                                   | `https://`로 시작하는 URL을 입력해 주세요                                                             | `image_url`, `landing_url`                                  |
| URL 접근 불가        | URL에 접근할 수 없어요                                              | 404, 403 오류가 없고 누구나 접근할 수 있는 URL인지 확인해 주세요. HTTP 200 응답이 필요해요                             | `image_url`, `landing_url`                                  |
| 지원하지 않는 파일 형식    | 지원하지 않는 이미지 형식이에요                                           | JPG, JPEG, PNG 중 하나로 바꿔 주세요                                                               | `image_url`                                                 |
| 이미지 해상도 미달 혹은 초과 | 이미지 크기가 500\*500px 보다 작거나 2048\*2048px 보다 커요                | 500\*500px 이상2048\*2048px 이하의 이미지로 바꿔주세요                                                  | `image_url`                                                 |
| 이미지 비율 오류        | 이미지 비율이 허용 범위를 벗어났어요                                        | 1:1 비율을 가장 권장해요. 최소한 5:7에서 7:5 사이로 맞춰 주세요                                                 | `image_url`                                                 |
| 이미지 파일 크기 초과     | 이미지 파일 크기가 최대 8MB를 초과해요                                     | 8MB 이하의 이미지로 교체해 주세요                                                                      | `image_url`                                                 |
| 투명 배경 사용         | 투명 배경인 알파 채널이 포함된 이미지는 쓸 수 없어요                              | 투명 배경이 없는 이미지로 바꿔 주세요                                                                     | `image_url`                                                 |
| 가격 오류            | 가격이 1원보다 작거나 숫자가 아니에요                                       | 1원 이상의 숫자로 수정해 주세요. 예를 들어 `10000` 또는 `10000 KRW`로 입력해요                                    | `price`                                                     |
| 가격 형식 오류         | 가격 형식이 맞지 않아요                                               | 숫자만 쓰거나 숫자 뒤에 `KRW`를 붙여 주세요. 예를 들어 `10000` 또는 `10000 KRW`로 입력해요                           | `price`                                                     |
| 지원하지 않는 값        | 허용하지 않는 값이 들어 있어요                                           | [카탈로그 연동 스펙의 허용값](/guide/catalog/spec.md)에 맞게 수정해 주세요                                     | `availability`, `same_day_shipping_available`, `gender`     |
| 추적 URL 형식 오류     | 전환 추적 URL에 필수 파라미터가 빠졌어요                                    | 앱 광고 성과 측정 도구별 필수 파라미터를 포함해 주세요. [앱 광고 성과 측정 연동(MAT)](/guide/tracking/mat.md)에서 확인할 수 있어요 | `landing_url`                                               |
| 상품 ID 중복         | 같은 상품 ID가 상품 목록에 두 번 이상 있어요. 가장 마지막 상품만 반영되고 나머지는 노출에서 제외돼요 | 상품 ID가 겹치지 않도록 수정해 주세요                                                                    | `id`                                                        |

### 권장 조치

| 문제             | 설명                                                                 | 해결 방법                                                                                                                 | 대상 상품 정보                                                                   |
| -------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 글자 수 초과        | 선택 상품 정보의 글자 수가 허용 범위를 벗어났어요                                       | [카탈로그 연동 스펙의 글자 수 제한](/guide/catalog/spec.md)에 맞게 수정해 주세요                                                             | `description`, `product_size`, `color`, `custom_label_0`\~`custom_label_4` |
| 할인 가격 오류       | 할인 가격이 1원보다 작거나 형식이 맞지 않거나 가격과 같거나 높아요. 이 경우 할인 가격 대신 가격만 광고에 노출돼요 | 할인 가격을 원화 형식으로 가격보다 낮게 입력해 주세요                                                                                        | `sale_price`                                                               |
| 할인 기간 형식 오류    | 할인 기간 형식이 맞지 않아요. 이 경우 할인 가격 대신 가격만 광고에 노출돼요                       | <p>ISO 8601 형식으로, 시작일과 종료일을 모두 입력해주세요.<br>예를 들어 <code>2025-01-01T00:00+09:00/2025-01-31T23:59+09:00</code>로 입력해요.</p> | `sale_price_effective_date`                                                |
| 할인 기간 범위 오류    | 할인 기간 시작일이 종료일보다 늦어요. 이 경우 할인 가격 대신 가격만 광고에 노출돼요                   | 시작일을 종료일보다 이른 날짜로 바꿔주세요.                                                                                              | `sale_price_effective_date`                                                |
| 출고 마감 시각 형식 오류 | 입력한 시간 형식이 맞지 않아요. 이 경우 해당 정보는 광고에 사용되지 않아요                        | 30분 단위, 24시간 형식인 `HH:mm`으로 입력해 주세요                                                                                    | `shipping_cutoff_time`                                                     |
| 출고 마감 시각 미입력   | 당일 출고 상품인데 출고 마감 시각이 비어 있어요                                        | `same_day_shipping_available`이 `true`라면 출고 마감 시각을 함께 입력해 주세요                                                          | `shipping_cutoff_time`                                                     |

### 심사 반려된 상품

상품 정보 문제를 모두 해결한 뒤 자동 등록은 다음 예약 업데이트를 기다리거나 즉시 업데이트를 진행하고, 수동 등록은 수정한 파일을 다시 등록해 주세요. 변경 사항이 반영되면 자동으로 심사가 진행돼요. 심사에서 반려되면 상품이 **노출 불가** 상태가 되고, 상품 상세에서 반려 사유를 확인할 수 있어요.

* 토스애즈 광고 정책에 따라 광고할 수 없는 카테고리 또는 상품이 있어요. [광고 불가 업종 안내](/guide/review/restrictedindustry.md)와 [카탈로그 운영·심사 정책](/guide/review/catalog.md)을 확인해 주세요.
* 이미지에서 상품을 식별하기 어렵거나 과도한 텍스트, 로고, 워터마크, 테두리, 여백이 있으면 반려될 수 있어요. 이미지를 수정한 뒤 자동 등록은 다음 예약 업데이트나 즉시 업데이트를 진행하고, 수동 등록은 수정한 파일을 다시 등록해 주세요.

상품 카테고리를 인식하지 못하면 토스애즈가 자동으로 다시 시도해요. 문제가 오래 지속되면 토스애즈 고객센터로 문의해 주세요.

## 성과가 측정되지 않을 때

카탈로그 연동에는 성공했지만 상품별 성과가 측정되지 않는다면, 카탈로그의 상품 ID와 전환 이벤트의 `product_id`가 같은 값인지 확인해 주세요.

* 값 앞뒤에 공백이나 불필요한 문자가 없는지 확인해 주세요.
* 대문자와 소문자를 같은 방식으로 쓰는지 확인해 주세요.
* 상품 조회, 장바구니 담기, 구매 이벤트가 모두 같은 기준의 `product_id`를 보내는지 확인해 주세요.

웹 광고는 [웹 광고 성과 측정 연동(토스 픽셀)](/guide/tracking/tosspixel.md), 앱 광고는 [앱 광고 성과 측정 연동(MAT)](/guide/tracking/mat.md)을 확인해 주세요.

## 자주 묻는 질문

**Q. 상품 등록 시 상품 ID가 중복되면 어떻게 되나요?**

중복된 상품 ID가 있으면 가장 마지막 상품만 반영되고 나머지 상품은 광고에 노출되지 않아요. 상품 ID는 고유한 값으로 설정해 주세요.

**Q. 자동 업데이트를 사용 중인데 상품을 삭제할 때 주의할 점이 있나요?**

삭제한 뒤 다음 자동 업데이트 때 원본 상품 목록에 해당 상품 ID가 포함되어 있으면, 삭제된 상품이 다시 유효한 상품으로 등록될 수 있어요. 업데이트와 관계없이 특정 상품을 광고에서 완전히 빼려면 삭제 대신 **광고 사용 여부**를 **미사용**으로 설정하는 것을 권장해요.

**Q. 광고 사용 여부를 미사용으로 바꾸면 자동 업데이트 후에도 유지되나요?**

네. 미사용 설정은 자동 업데이트와 관계없이 유지돼요. 상품 정보는 업데이트되지만 광고에는 노출되지 않아요.

**Q. 자동 등록을 사용하면 최초 등록 시에는 등록되지 않나요?**

아니요. 최초 등록은 즉시 진행돼요. 이후 등록은 설정한 시간에 맞춰 주기적으로 진행돼요. 최초 등록이 오래 걸려 다음 등록 예정 시간을 지난 경우에는 최초 등록이 끝난 뒤 지연된 일정으로 한 번 더 업데이트가 진행돼요.

**Q. 재고가 다시 생기면 바로 광고에 노출되나요?**

원본 상품 목록의 재고 값을 `in stock` 또는 `available for order`로 바꾸고 다음 업데이트가 성공했는지 확인해 주세요. 상품이 **노출 가능** 상태이고 **광고 사용 여부**가 **사용**이면 광고 대상에 포함돼요.

**Q. 광고 가능 상품이 하나도 없어요.**

캠페인에서 사용할 수 있는 상품이 없는 상태예요. 필수 상품 정보, 오류 표의 항목, 재고 상태, 심사 반려 사유를 차례로 확인하고 상품을 다시 등록해 주세요.

## 문의하기

문제가 해결되지 않으면 토스애즈 고객센터로 문의해 주세요. 다음 정보를 함께 보내면 더 빠르게 확인할 수 있어요.

* 카탈로그명
* 카탈로그 ID
* 등록 방식(자동 또는 수동)
* 문제가 발생한 시각과 마지막으로 성공한 업데이트 시각
* 화면에 표시된 오류 메시지 또는 문제 보고서
* 영향을 받은 상품 ID 예시


---

# 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://toss-ads.gitbook.io/guide/catalog/troubleshooting.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.