오류

EasterAd Core API는 요청 처리 중 오류가 발생하면 HTTP 상태 코드와 일관된 규격의 JSON 에러 응답을 반환합니다. 클라이언트는 오류 코드(code)를 기준으로 예외 처리를 분기합니다.

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으로 분기하며, 소재 상태 조회와 재시도는 콘솔에서 지원하므로 콘솔의 소재 준비 상태에서 확인하고 조치합니다.

권한 및 기능 거절 정보

권한 검사에서 반환하는 403 응답에는 선택 필드 authorization이 포함됩니다.

필드	의미
`reason` (`number`)	`1`: 권한 부족, `2`: 기능 비활성
`condition` (`number`)	`1`: 모두 필요한 권한, `2`: 하나 이상 필요한 권한
`permissions` (객체 배열)	각 항목의 `label`은 한국어 설명, `statement`는 조직·자원 ID를 포함한 권한 원문

permissions는 요청이 거부된 권한을 표시합니다. authorization은 선택 필드이므로 code에 따른 오류 처리도 구현합니다. 표시된 권한을 보완한 뒤 다시 호출해 추가로 필요한 권한을 확인합니다.

2. 요청 오류별 조치

요청이 실패하면 아래 조치를 적용합니다.

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

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

인증 오류가 반환되면 아래 조치를 적용합니다.

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

4. 403 오류 해결하기

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["문의하기로 문의"]

호출 서버의 IP 등록 상태를 확인합니다. 응답의 code가 IP_NOT_WHITELISTED인지 확인합니다. 등록되지 않은 IP라면 대시보드의 API 키 정책 설정에서 호출하는 서버의 고정 공인 IP를 등록합니다.
조직 기능의 활성화 여부를 점검합니다. 조직에 해당 비즈니스 기능(광고주 기능, 퍼블리셔 기능 등)이 켜져 있는지 확인합니다. 기능이 비활성화된 상태에서는 권한이 있더라도 접근할 수 없으므로 조직 관리자에게 기능 활성화를 요청합니다.
API 키 역할의 권한 범위를 점검합니다. API 키에 배정된 역할이 해당 API에 필요한 권한을 포함하는지 확인합니다. 권한이 부족하다면 조직 관리자에게 권한 부여를 요청합니다. 역할 수정 방법은 멤버와 역할 관리에서 확인합니다.

세 단계를 모두 확인한 후에도 오류가 지속되면 문의하기로 문의합니다.

다음 단계

페이지네이션 및 API 규약: 목록 응답 처리 패턴과 데이터 명명 규칙을 확인합니다.
요청 제한(Rate Limits): 호출 한도와 지수 백오프 전략을 확인합니다.