콘텐츠로 이동
EasterAdEasterAdDocs

오류

EasterAd Core API는 요청 처리 중 오류가 발생했을 때 RFC 표준 HTTP 상태 코드와 함께 일관된 규격의 JSON 에러 페이로드를 반환합니다. 클라이언트 애플리케이션은 사용자용 메시지(message)가 아닌 머신 판독용 에러 코드(code)를 기준으로 예외 처리 분기를 구성해야 합니다.

1. 표준 오류 응답 구조

섹션 제목: “1. 표준 오류 응답 구조”

모든 실패 응답(4xx, 5xx)은 다음 3대 필수 필드를 포함합니다.

{
  "statusCode": 409,
  "code": "Conflict",
  "message": "Completed campaigns cannot be edited"
}
필드명 타입 설명
statusCode number HTTP 응답 상태 코드(400, 401, 403, 404, 409, 429, 500 등)와 동일한 정수입니다.
code string 프로그래밍 분기 처리를 위한 고유 에러 식별자입니다.
message string 오류 원인을 설명하는 사람이 읽을 수 있는 안내 문구입니다. (향후 변경될 수 있음)

소재가 아직 준비되지 않은 상태에서 캠페인에 연결하면 HTTP 409 응답에 선택 필드 reason: "CREATIVE_NOT_READY"와 해당 assetId가 포함됩니다. code와 reason으로 분기하고 그 소재의 상태를 조회하세요.

소재 처리 자체의 실패는 상태 조회가 성공한 HTTP 200 응답에서도 status: "FAILED"로 나타납니다. 이때는 errorReason, errorMessage, retryable을 확인합니다. retryable이 참일 때만 같은 원본을 재시도하세요. 입력 오류는 다른 원본이 필요하고, 서버 설정 오류는 운영자의 조치가 필요합니다.

2. 일반 비즈니스 오류 코드 카탈로그

섹션 제목: “2. 일반 비즈니스 오류 코드 카탈로그”

비즈니스 로직 처리 및 데이터 검증 단계에서 발생하는 대표적인 코드입니다.

HTTP 상태 에러 코드 (code) 주요 발생 원인 및 해결 방안
400 BadRequest 필드 타입 위반, 필수 파라미터 누락, 유효하지 않은 Enum 문자열 전달 시 발생합니다.
401 Unauthorized API 키 누락, 오타, 만료 등 자격증명이 올바르지 않은 경우입니다. (하단 인증 코드 참조)
403 Forbidden API 키의 역할에 작업 권한이 없거나, 해당 조직에 기능이 비활성화된 상태입니다.
404 NotFound 요청한 ID의 리소스가 존재하지 않거나, 호출자가 접근할 수 없는 조직 범위입니다.
409 Conflict 리소스의 현재 상태와 충돌하는 요청입니다. (예: 종료된 캠페인 수정, 지갑 잔액 부족, 지면당 광고 단위 중복, SDK 키 발급 상한 초과 등)
429 TooManyRequests 초당/시간당 API 호출 한도를 초과했습니다. 요청 제한 정책을 참고하세요.
500 InternalServerError 서버 내부 일시적 오류입니다. 잠시 후 재시도하고 문제가 지속되면 기술팀에 문의하세요.
503 ServiceUnavailable 일시적인 서비스 점검 또는 백엔드 의존성 장애입니다. 지수 백오프 후 재시도하세요.

3. 인증 단계 전용 오류 코드

섹션 제목: “3. 인증 단계 전용 오류 코드”

API 게이트웨이 인증 필터에서 발생하는 전용 에러 코드 체계입니다.

HTTP 상태 에러 코드 (code) 상세 원인 및 조치 방법
401 UNAUTHORIZED Authorization: Bearer 헤더 자체가 누락되었습니다. 헤더를 포함하여 다시 호출하세요.
401 INVALID_API_KEY 키 포맷 오류, 폐기되었거나 삭제된 키, 비활성화된 계정입니다. 새 키를 발급받으세요.
401 API_KEY_EXPIRED 키의 설정된 만료일이 지났습니다. 만료일을 갱신하거나 새 키로 교체하세요.
403 IP_NOT_WHITELISTED 키 정책에 등록된 허용 IP 목록 밖에서 요청이 들어왔습니다. 호출 서버 공인 IP를 등록하세요.
429 RATE_LIMIT_EXCEEDED 키의 시간당 한도 초과 또는 잘못된 키 인증 실패 반복으로 해당 IP가 일시 차단되었습니다.

4. 403 Forbidden 트러블슈팅 3단계 체크리스트

섹션 제목: “4. 403 Forbidden 트러블슈팅 3단계 체크리스트”

API 호출 시 403 오류를 마주쳤다면 아래 순서대로 원인을 격리하여 디버깅하세요.

flowchart TD
    A["403 오류 발생"] --> B{"1. IP 차단인가? (code === 'IP_NOT_WHITELISTED')"}
    B -- Yes --> C["대시보드 API 키 정책에서 호출 서버 IP 추가"]
    B -- No --> D{"2. 조직 기능이 켜져 있는가?"}
    D -- No --> E["조직 설정에서 광고주/퍼블리셔 등 기능 활성화"]
    D -- Yes --> F{"3. 역할에 해당 권한이 있는가?"}
    F -- No --> G["멤버 관리 > 역할 설정에서 엔드포인트 작업 권한 부여"]
    F -- Yes --> H["기술 지원팀 문의"]
  1. 1단계: IP 화이트리스트 확인
    • 응답의 code가 IP_NOT_WHITELISTED인지 확인합니다. 만약 그렇다면 대시보드의 API 키 정책 설정에서 호출하는 서버의 고정 공인 IP를 등록합니다.
  2. 2단계: 조직 기능 활성화 여부 점검
    • 조직 자체에 해당 비즈니스 기능(예: 광고주 기능, 퍼블리셔 기능, 과금 기능)이 켜져 있는지 확인합니다. 기능이 꺼진 상태에서는 권한이 있더라도 접근할 수 없습니다.
  3. 3단계: API 키 역할의 권한 스코프 점검
    • API 키에 부여된 역할이 엔드포인트가 요구하는 권한(예: 캠페인 생성, 잔액 조회 등)을 포함하고 있는지 조직 설정 → 멤버 및 역할에서 확인하고 역할을 업데이트합니다.

다음 단계

섹션 제목: “다음 단계”