API Rate Limit 안내

기본 정책

Violz API는 서비스 안정성을 위해 모든 요청에 Rate Limit(요청 제한)을 적용합니다.

제한은 IP 주소 기준으로 적용됩니다.

제한 초과 시

Rate Limit을 초과하면 HTTP 429 (Too Many Requests) 응답이 반환됩니다.

{
  "statusCode": 429,
  "message": "Too many requests. Please try again later.",
  "retryAfter": 3
}

응답 헤더

모든 API 응답에는 Rate Limit 관련 헤더가 포함됩니다.

커스텀 규칙

특정 IP, 사용자, 경로에 대해 별도의 Rate Limit 규칙을 적용할 수 있습니다.

우선순위

여러 규칙이 동시에 해당될 경우, 아래 우선순위에 따라 하나의 규칙만 적용됩니다.

1. 사용자 키(userKey) — 가장 높은 우선순위
2. IP 주소 — 특정 IP에 대한 규칙
3. 경로(Path) — 특정 API 경로에 대한 규칙
4. 기본 규칙 — 위 규칙에 해당하지 않는 경우

규칙 유형

IP 규칙

특정 IP 주소에 대해 별도의 제한을 설정합니다.

• 예: 사내 IP에 대해 더 높은 제한 허용

사용자 키 규칙

특정 사용자(userKey)에 대해 별도의 제한을 설정합니다.

• 예: PRO 요금제 사용자에게 더 높은 제한 허용

경로 규칙

특정 API 경로에 대해 별도의 제한을 설정합니다.

• 경로는 prefix 매칭으로, 더 긴(구체적인) 경로가 우선 적용됩니다.
• 예: /messages/v1/send 경로에 더 엄격한 제한 적용

권장 사항

• 재시도 로직: 429 응답 수신 시 Retry-After 헤더 값만큼 대기 후 재시도하세요.
• 요청 최적화: 불필요한 반복 호출을 줄이고, 가능하면 배치 API를 활용하세요.
• 제한 상향 요청: 기본 제한이 부족한 경우, 관리자에게 커스텀 규칙 설정을 요청하세요.

문의

Rate Limit 관련 문의는 관리자에게 연락해 주세요.