오류 처리

Blitz Rocket API는 표준 HTTP 상태 코드를 사용하며 일관된 오류 응답 본문을 반환합니다.

HTTP 상태 코드

상태 코드	의미
`200`	성공 — 요청이 성공적으로 처리됨
`201`	생성됨 — 리소스가 성공적으로 생성됨
`400`	잘못된 요청 — 잘못된 매개변수 또는 필수 필드 누락
`401`	인증 실패 — API 키 누락 또는 유효하지 않음
`403`	금지됨 — 권한 부족 (예: 비공개 엔드포인트에 공개 키 사용)
`404`	찾을 수 없음 — 리소스가 존재하지 않음
`429`	너무 많은 요청 — 속도 제한 초과
`500`	내부 서버 오류 — 당사 서버에서 문제 발생

오류 응답 형식

모든 오류 응답은 다음 구조를 따릅니다:

json

{
  "success": false,
  "error": "오류에 대한 사람이 읽을 수 있는 설명"
}

일반적인 오류

API 키 누락

json

// 상태: 401
{
  "success": false,
  "error": "API 키가 누락되었거나 유효하지 않습니다"
}

비공개 키 필요

json

// 상태: 403
{
  "success": false,
  "error": "이 엔드포인트는 비공개 API 키가 필요합니다"
}

리소스 찾을 수 없음

json

// 상태: 404
{
  "success": false,
  "error": "콘테스트를 찾을 수 없습니다"
}

검증 오류

json

// 상태: 400
{
  "success": false,
  "error": "이메일 또는 전화번호 중 하나는 필수입니다"
}

코드에서 오류 처리하기

javascript

async function makeApiRequest(endpoint) {
  const response = await fetch(`https://blitzrocket.com/api/v1${endpoint}`, {
    headers: { "x-api-key": process.env.BLITZROCKET_API_KEY },
  });

  const data = await response.json();

  if (!data.success) {
    switch (response.status) {
      case 401:
        throw new Error("유효하지 않은 API 키입니다. 자격 증명을 확인하세요.");
      case 403:
        throw new Error("권한이 부족합니다. 비공개 API 키를 사용하세요.");
      case 404:
        throw new Error(`리소스를 찾을 수 없습니다: ${data.error}`);
      case 429:
        throw new Error("속도 제한에 걸렸습니다. 백오프로 재시도하세요.");
      default:
        throw new Error(`API 오류: ${data.error}`);
    }
  }

  return data.data;
}