에러 및 요청 제한

에러 형식

모든 에러는 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만 반환됩니다.