에러 코드

아래가 이 문서에 실린 엔드포인트가 반환하는 전부입니다.

응답 형식

application/json

{
  "error": "Invalid or missing API key"
}

error 는 항상 문자열 한 줄입니다. code·status·details·message 같은 중첩 필드는 없습니다. 응답 본문 대신 HTTP 상태 코드로 분기하세요.

아래 상태 코드 목록은 이 문서에 실린 엔드포인트가 응답할 때의 이야기입니다. 문서에 없는 경로·문서에 없는 메서드(예: 조회 전용 경로에 POST)는 이 목록의 대상이 아닙니다.

파싱 전에 Content-Type 을 확인하세요

본문을 JSON 으로 파싱하기 전에 응답의 Content-Type 이 application/json 인지 확인하세요. 경로를 잘못 적으면 API 가 아닌 다른 응답(웹페이지 HTML 등)을 받을 수 있고, 그때는 상태 코드만 봐서는 실패를 알아채지 못합니다.

상태 코드 전수

성공은 200 하나입니다(생성 응답 201 은 읽기 전용 단계에 없습니다). 오류로 나올 수 있는 코드는 401 · 403 · 404 · 429 · 500 입니다.

코드	응답 본문	언제 나오나
`401`	`{"error":"Invalid or missing API key"}`	Authorization 헤더가 없거나, 키가 폐기·만료됐거나, 값에 오타가 있는 경우입니다.
`403`	`{"error":"API 접근 자격이 없습니다. Pro 플랜 구독이 필요합니다."}`	키는 유효하지만 소유 계정이 지금 Pro 가 아닌 경우입니다(플랜 강등·구독 만료 포함). 매 요청 다시 확인합니다.
`404`	`{"error":"Campaign not found"}`	캠페인이 없거나, 있어도 내 브랜드 소유가 아닌 경우입니다. 남의 캠페인이 존재하는지 알려주지 않으려고 두 경우를 같은 404 로 응답합니다.
`404`	`{"error":"Not Found"}`	/api/v1 아래 존재하지 않는 경로를 부른 경우입니다. code="unknown_endpoint" 와 함께 옵니다(웹페이지 HTML 이 아니라 항상 JSON).
`429`	`{"error":"Rate limit exceeded"}`	IP 분당 300회 또는 키 분당 60회를 넘긴 경우입니다. 어느 쪽이 걸렸는지는 응답으로 구분되지 않습니다.
`500`	`{"error":"Failed to fetch applicants"}`	지원자 목록을 읽지 못한 경우입니다(일시 장애).
`500`	`{"error":"Failed to fetch campaign"}`	캠페인 상세를 읽지 못한 경우입니다(일시 장애).
`500`	`{"error":"Failed to fetch campaigns"}`	캠페인 목록을 읽지 못한 경우입니다(일시 장애).
`500`	`{"error":"Failed to fetch influencers"}`	인플루언서 검색이 실패한 경우입니다(일시 장애).
`500`	`{"error":"Failed to fetch proposals"}`	제안 목록을 읽지 못한 경우입니다(일시 장애).
`500`	`{"error":"Failed to resolve brand scope"}`	내 브랜드 목록을 읽지 못한 경우입니다(일시 장애). 잠시 후 다시 시도하세요.

401
응답 본문
{"error":"Invalid or missing API key"}
언제 나오나
Authorization 헤더가 없거나, 키가 폐기·만료됐거나, 값에 오타가 있는 경우입니다.
403
응답 본문
{"error":"API 접근 자격이 없습니다. Pro 플랜 구독이 필요합니다."}
언제 나오나
키는 유효하지만 소유 계정이 지금 Pro 가 아닌 경우입니다(플랜 강등·구독 만료 포함). 매 요청 다시 확인합니다.
404
응답 본문
{"error":"Campaign not found"}
언제 나오나
캠페인이 없거나, 있어도 내 브랜드 소유가 아닌 경우입니다. 남의 캠페인이 존재하는지 알려주지 않으려고 두 경우를 같은 404 로 응답합니다.
404
응답 본문
{"error":"Not Found"}
언제 나오나
/api/v1 아래 존재하지 않는 경로를 부른 경우입니다. code="unknown_endpoint" 와 함께 옵니다(웹페이지 HTML 이 아니라 항상 JSON).
429
응답 본문
{"error":"Rate limit exceeded"}
언제 나오나
IP 분당 300회 또는 키 분당 60회를 넘긴 경우입니다. 어느 쪽이 걸렸는지는 응답으로 구분되지 않습니다.
500
응답 본문
{"error":"Failed to fetch applicants"}
언제 나오나
지원자 목록을 읽지 못한 경우입니다(일시 장애).
500
응답 본문
{"error":"Failed to fetch campaign"}
언제 나오나
캠페인 상세를 읽지 못한 경우입니다(일시 장애).
500
응답 본문
{"error":"Failed to fetch campaigns"}
언제 나오나
캠페인 목록을 읽지 못한 경우입니다(일시 장애).
500
응답 본문
{"error":"Failed to fetch influencers"}
언제 나오나
인플루언서 검색이 실패한 경우입니다(일시 장애).
500
응답 본문
{"error":"Failed to fetch proposals"}
언제 나오나
제안 목록을 읽지 못한 경우입니다(일시 장애).
500
응답 본문
{"error":"Failed to resolve brand scope"}
언제 나오나
내 브랜드 목록을 읽지 못한 경우입니다(일시 장애). 잠시 후 다시 시도하세요.

쓰기를 시도했을 때

1단계 키는 읽기 전용이라 쓰기 경로는 거부됩니다. 실제 응답은 다음과 같습니다.

요청	코드	응답 본문
`POST /campaigns`	`403`	`{"error":"이 API 키는 읽기 전용입니다. 캠페인 생성(쓰기) API 는 현재 준비 중입니다."}`
`POST /messages`	`403`	`{"error":"이 API 키는 읽기 전용입니다. 메시지 발송(쓰기)은 지원되지 않습니다."}`

POST /campaigns
코드
403
응답 본문
{"error":"이 API 키는 읽기 전용입니다. 캠페인 생성(쓰기) API 는 현재 준비 중입니다."}
POST /messages
코드
403
응답 본문
{"error":"이 API 키는 읽기 전용입니다. 메시지 발송(쓰기)은 지원되지 않습니다."}

본문 문자열로 분기하지 마세요

오류 문자열은 안내용이라 문구가 다듬어질 수 있습니다. 프로그램 분기는 항상 HTTP 상태 코드로 하세요. 같은 429라도 원인이 IP 한도인지 키 한도인지는 본문으로 구분되지 않습니다 — 호출 한도 문서를 참고하세요.