에러와 요청 제한

에러 형식

모든 에러는 JSON 본문을 반환합니다.

{
  "message": "Human-readable description",
  "code": "MACHINE_READABLE_CODE"
}

인증 에러에는 추가로 authenticated 필드가 포함됩니다.

{
  "message": "Invalid API key",
  "code": "INVALID_API_KEY_EXCEPTION",
  "authenticated": false
}

HTTP 상태 코드

상태	의미
400 Bad Request	필수 필드 누락, 유효하지 않은 값, 또는 제약 조건 위반
401 Unauthorized	API 키가 없거나 유효하지 않음
403 Forbidden	인증되었지만 이 작업을 수행할 권한이 없음
404 Not Found	리소스가 존재하지 않거나 현재 권한으로 접근할 수 없음
429 Too Many Requests	요청 제한 초과
500 Internal Server Error	예상치 못한 서버 에러

요청 제한

각 엔드포인트에는 요청 제한을 결정하는 티어가 할당됩니다. 카운터는 라우트별로 계산되며, 같은 계정이 소유한 모든 API 키가 공유합니다.

티어	제한	기간	차단 시간
Tier 1	5회	5분	30분
Tier 2	5회	1분	10분
Tier 3	20회	1분	10분
Tier 4	60회	1분	10분

모든 응답에는 다음 헤더가 포함됩니다.

헤더	설명
x-ratelimit-limit	현재 윈도우의 최대 요청 수
x-ratelimit-remaining	현재 윈도우에서 남은 요청 수
x-ratelimit-reset	현재 윈도우가 리셋될 때까지 남은 초

차단 중에는 429 상태와 함께 x-ratelimit-reset만 반환됩니다.