오류 처리

모든 오류는 같은 형식으로 반환됩니다. code로 분기하고, message는 사람이 읽는 용도로만 사용하세요.

{
  "code": "PROMPT_SET_NOT_FOUND",
  "message": "프롬프트 세트를 찾을 수 없습니다"
}

검증 오류는 details에 필드별 위반 내용이 배열로 포함됩니다.

{
  "code": "COMMON_VALIDATION",
  "message": "데이터 검증에 실패했습니다",
  "details": [
    "models: 최소 1개 이상이어야 합니다",
    "keywords: 최대 100개까지 입력할 수 있습니다"
  ]
}

오류 메시지는 Accept-Language 헤더에 따라 한국어(ko) 또는 영어(en)로 반환됩니다. 헤더가 없거나 지원하지 않는 언어면 영어로 반환됩니다. code 값은 언어와 무관하게 항상 같습니다.

HTTP 상태 코드

상태	의미	대응
`400`	잘못된 요청 (검증 실패, 잘못된 cursor 등)	요청을 수정한 뒤 재시도. 같은 요청의 재시도는 무의미합니다
`401`	인증 실패	`API-Key` 헤더와 키 값 확인
`402`	크레딧 부족 (`INSUFFICIENT_CREDITS`)	`GET /credits/me`로 잔액 확인 후 충전. 크레딧 참고
`404`	리소스 없음	ID가 내 조직의 리소스인지 확인
`409`	상태 충돌 (예: 세트당 프롬프트 1,000개 초과)	리소스 상태를 확인한 뒤 요청 조정
`413`	요청 본문이 2MiB 초과 (`COMMON_REQUEST_BODY_TOO_LARGE`)	요청을 나눠 보내기
`429`	요청 한도 초과	`Retry-After` 헤더만큼 대기 후 재시도. Rate Limit 참고
`5xx`	서버 오류 또는 외부 공급자 장애	지수 백오프로 재시도

공통 오류 코드

엔드포인트를 가리지 않고 발생하는 코드입니다. 이 코드들의 처리 로직은 한 번 만들어 두고 모든 호출에 재사용하세요.

코드	HTTP	설명
`COMMON_BINDING`	400	요청 본문을 해석할 수 없음 (JSON 형식 오류 등)
`COMMON_VALIDATION`	400	필드 검증 실패. `details`에 위반 목록
`COMMON_INVALID_CURSOR`	400	cursor 형식 오류. 첫 페이지부터 다시 조회
`PLATFORM_INVALID_ID`	400	리소스 ID 형식 오류. 없는 리소스가 아니라 형식 문제이므로 `404`가 아닌 `400`입니다
`COMMON_UNAUTHORIZED`	401	인증 실패
`INSUFFICIENT_CREDITS`	402	크레딧 부족
`COMMON_REQUEST_BODY_TOO_LARGE`	413	요청 본문 2MiB 초과
`PLATFORM_RATE_LIMIT_EXCEEDED`	429	요청 한도 초과

엔드포인트별 오류

PROMPT_SET_NOT_FOUND, RUN_TOO_MANY_TASKS처럼 특정 리소스에서만 나는 코드는 여기서 다루지 않습니다. 각 API Reference 페이지 상단의 오류 표에 해당 엔드포인트에서 실제로 발생하는 코드만 정리돼 있습니다. 이 표는 API 스펙에서 자동 생성되므로 서버와 항상 일치합니다.

코드 접두사가 리소스를 가리킵니다. 프롬프트는 QUESTION_, 브랜드는 USER_BRAND_, 프롬프트 세트는 PROMPT_SET_, 실행 요청은 RUN_ 입니다.

재시도 전략

429 — Retry-After 헤더의 초만큼 대기 후 재시도합니다.
502 / 503 — 외부 공급자 장애일 수 있습니다. 지수 백오프(예: 1초 → 2초 → 4초)로 재시도합니다.
400 / 404 — 재시도해도 결과가 같습니다. 요청을 수정하세요.
폴링 중 일시적 오류가 나도 실행 수집 자체는 백그라운드에서 계속 진행됩니다. 다음 폴링에서 이어서 확인하면 됩니다.

시작하기

인증

가이드

MCP

HTTP 상태 코드

공통 오류 코드

엔드포인트별 오류

재시도 전략

​HTTP 상태 코드

​공통 오류 코드

​엔드포인트별 오류

​재시도 전략

HTTP 상태 코드

공통 오류 코드

엔드포인트별 오류

재시도 전략