에러 코드

API 에러 응답 형식과 에러 코드 목록입니다.

에러 응답 형식

모든 에러 응답은 아래 형식을 따릅니다.

ErrorResponse


{
  meta: {
    version: string      // API 버전
    requestId: string    // 요청 ID (문의 시 첨부)
    timestamp: string    // 응답 시간 (ISO 8601)
  }
  status: number         // HTTP 상태 코드
  type: string           // 에러 타입
  message: string        // 에러 메시지
  errors?: {             // 상세 오류 (Validation 에러 시)
    field: string        // 필드명
    message: string      // 오류 메시지
    value: any           // 전달된 값
  }[]
}

에러 응답 예시

Example: Validation Error


{
  "meta": {
    "version": "2026-01-11",
    "requestId": "abc123-def456",
    "timestamp": "2025-01-15T12:00:00Z"
  },
  "status": 400,
  "type": "VALIDATION_ERROR",
  "message": "요청 데이터 검증에 실패했습니다.",
  "errors": [
    {
      "field": "title",
      "message": "제목은 필수 항목입니다.",
      "value": null
    },
    {
      "field": "difficulty",
      "message": "난이도는 1~5 사이의 값이어야 합니다.",
      "value": 10
    }
  ]
}

문의 시 requestId를 함께 첨부하면 빠른 문제 해결이 가능합니다.

HTTP 상태 코드

상태 코드	설명
200	성공
201	생성 성공
204	삭제 성공 (응답 본문 없음)
400	잘못된 요청
401	인증 필요
403	접근 권한 없음
404	리소스 없음
429	요청 한도 초과
500	서버 내부 오류

에러 코드 목록

400 Bad Request

에러 코드	설명	해결 방법
`VALIDATION_ERROR`	요청 값 검증 실패	`errors` 배열에서 상세 오류 확인
`MISSING_PARAMETER`	필수 파라미터 누락	필수 파라미터를 모두 포함하여 재요청
`INVALID_REQUEST_BODY`	요청 본문 파싱 오류	JSON 형식이 올바른지 확인
`INVALID_PARAMETER`	잘못된 파라미터 값	파라미터 값 형식 및 범위 확인

401 Unauthorized

에러 코드	설명	해결 방법
`AUTHENTICATION_REQUIRED`	인증이 필요한 요청	Authorization 헤더 추가
`INVALID_TOKEN`	유효하지 않은 토큰	토큰 재발급 후 재시도
`TOKEN_EXPIRED`	만료된 토큰	Refresh Token으로 재발급
`INVALID_API_KEY`	유효하지 않은 API Key	API Key 확인 및 재발급

403 Forbidden

에러 코드	설명	해결 방법
`ACCESS_DENIED`	접근 권한 없음	필요한 권한(scope) 확인
`PERMISSION_DENIED`	리소스 권한 부족	리소스 소유자 권한 필요
`INSUFFICIENT_SCOPE`	OAuth scope 부족	추가 scope 요청 후 재인증

404 Not Found

에러 코드	설명	해결 방법
`RESOURCE_NOT_FOUND`	리소스를 찾을 수 없음	ID 또는 경로 확인
`CHANNEL_NOT_FOUND`	채널을 찾을 수 없음	채널 ID/webPath 확인
`SONG_NOT_FOUND`	노래를 찾을 수 없음	노래 ID 확인
`CONTENT_NOT_FOUND`	콘텐츠를 찾을 수 없음	콘텐츠 ID 확인

429 Too Many Requests

에러 코드	설명	해결 방법
`RATE_LIMIT_EXCEEDED`	Rate Limit 초과	`X-RateLimit-Reset` 이후 재시도
`QUOTA_EXCEEDED`	월간 쿼터 초과	다음 달까지 대기 또는 티어 업그레이드

500 Internal Server Error

에러 코드	설명	해결 방법
`INTERNAL_ERROR`	서버 내부 오류	`requestId`와 함께 문의
`SERVICE_UNAVAILABLE`	서비스 일시 불가	잠시 후 재시도

Rate Limit 관련 헤더

API 응답에 포함되는 Rate Limit 정보입니다.

헤더	설명
`X-RateLimit-Limit`	분당 최대 요청 수
`X-RateLimit-Remaining`	남은 요청 수
`X-RateLimit-Reset`	제한 초기화 시간 (Unix timestamp)

API Key 사용 시 추가 헤더

헤더	설명
`X-Quota-Limit`	월간 최대 요청 수
`X-Quota-Used`	이번 달 사용량
`X-Quota-Remaining`	남은 월간 요청 수
`X-Quota-Reset`	쿼터 초기화 일시 (ISO 8601)

Rate Limit 초과 시 429 응답이 반환됩니다. X-RateLimit-Reset 시간 이후에 재시도하세요.

에러 처리 예시

JavaScript

error-handler.js


async function apiRequest(url, options = {}) {
  const response = await fetch(url, options);
 
  if (!response.ok) {
    const error = await response.json();
 
    switch (error.type) {
      case 'VALIDATION_ERROR':
        console.error('검증 오류:', error.errors);
        break;
      case 'RATE_LIMIT_EXCEEDED':
        const resetTime = response.headers.get('X-RateLimit-Reset');
        console.error(`Rate Limit 초과. ${new Date(resetTime * 1000)} 이후 재시도`);
        break;
      case 'TOKEN_EXPIRED':
        // 토큰 갱신 로직
        await refreshToken();
        return apiRequest(url, options);
      default:
        console.error(`에러 [${error.type}]: ${error.message}`);
    }
 
    throw error;
  }
 
  return response.json();
}

멜로밍Developers