에러와 요청 제한

에러 형식

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

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

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

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

HTTP 상태 코드

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

요청 제한

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

Tier	Limit	Window	Block duration
Tier 1	5 requests	5 minutes	30 minutes
Tier 2	5 requests	1 minute	10 minutes
Tier 3	20 requests	1 minute	10 minutes
Tier 4	60 requests	1 minute	10 minutes

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

Header	Description
x-ratelimit-limit	분당 최대 요청 수
x-ratelimit-remaining	현재 윈도우에서 남은 요청 수
x-ratelimit-reset	윈도우가 리셋되는 타임스탬프

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