에러 처리 - Chainshift

모든 에러는 같은 형식으로 반환됩니다. 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_VALIDATION`	400	필드 검증 실패. `details`에 위반 목록
`COMMON_INVALID_CURSOR`	400	cursor 형식 오류. 첫 페이지부터 다시 조회
`COMMON_UNAUTHORIZED`	401	인증 실패
`RUN_PROMPT_TARGET_REQUIRED`	400	`promptIDs`·`promptSetID` 지정 오류
`RUN_TOO_MANY_TASKS`	400	실행 요청 하나의 총 실행 수 10,000개 초과
`PROMPT_SET_NOT_FOUND`	404	프롬프트 세트 없음
`PROMPT_SET_EMPTY`	400	빈 세트로 실행 요청
`PROMPT_SET_PROMPT_LIMIT_EXCEEDED`	409	세트당 프롬프트 1,000개 초과
`QUESTION_NOT_FOUND`	404	프롬프트 없음 (조회·수정·삭제 시)
`PROMPT_NOT_FOUND`	404	실행 요청의 `promptIDs`에 없는 프롬프트 포함
`ANSWER_NOT_FOUND`	404	답변 없음
`USER_BRAND_NOT_FOUND`	404	브랜드 없음
`MODEL_NOT_SUPPORTED`	400	지원하지 않는 모델
`REGION_NOT_SUPPORTED_FOR_MODEL`	400	모델이 지원하지 않는 지역
`INSUFFICIENT_CREDITS`	402	크레딧 부족
`PLATFORM_RATE_LIMIT_EXCEEDED`	429	요청 한도 초과

프롬프트 관련 에러는 QUESTION_, 브랜드 관련 에러는 USER_BRAND_ 접두사를 사용합니다. 각각 프롬프트·브랜드 리소스를 가리킵니다.

재시도 전략

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