메인 콘텐츠로 건너뛰기

속도 제한

속도 제한은 애플리케이션이 지정된 시간 내에 API에 요청할 수 있는 최대 횟수를 정의합니다. 이 메커니즘은 서비스의 전반적인 상태와 신뢰성을 유지하는 데 매우 중요합니다.

속도 제한을 사용하는 이유​

API stability and performance
  • 단일 클라이언트가 과도한 요청으로 서버를 압도하는 것을 방지합니다.
  • 모든 클라이언트에 대해 일관되고 예측 가능한 응답 시간을 보장합니다.
  • 예상치 못한 트래픽 급증으로부터 백엔드 서비스를 보호합니다.
  • 인프라에서 안정적이고 제어된 부하 패턴을 유지합니다.
Security
  • 무차별 대입과 같은 공격 시도에 대한 방어를 강화합니다.
  • 분산 서비스 거부(DDoS) 위험을 완화합니다.
  • 잘못 구현된 통합으로 인한 영향을 줄입니다.
  • 손상된 API 자격 증명으로 인한 잠재적 피해를 제한합니다.
Resource allocation
  • 모든 클라이언트에 API 리소스에 대한 균형 잡힌 접근을 보장합니다.
  • 일부의 남용적 사용이 다른 사용자의 경험을 저하시키는 것을 방지합니다.
  • 비즈니스 기준과 필요에 따라 트래픽 우선순위를 정할 수 있습니다.
  • 보다 효율적이고 지속 가능한 API 소비 관행을 장려합니다.

속도 제한 작동 방식​

각 API 호출은 초당 허용 요청 한도에 산입됩니다. 기본값은 테넌트당 10 RPS입니다. 한도를 초과하면 API는 HTTP 429 Too Many Requests를 반환합니다.

온보딩 팀에 확인하세요

정확한 한도는 테넌트별로 구성됩니다. 고처리량 통합을 위해 크기를 조정하기 전에 온보딩 팀에 연락하여 계정에 적용된 한도를 확인하세요.

429 오류 처리​

Request a rate limit increase

운영상 요청 볼륨이 증가할 경우(일시적 또는 영구적), Unico 팀에 알려 환경의 속도 제한을 높여달라고 요청하세요. 이 요청은 볼륨이 실제로 증가하기 전에 이루어져야 하며, 그렇지 않으면 애플리케이션이 작동 불능 상태가 될 수 있습니다.

Review application behavior
  • 비효율적인 API 사용 패턴을 식별하기 위해 코드를 감사하세요.
  • 의도하지 않은 루프나 중복 API 호출을 확인하세요.
  • 대규모 버스트로 전송하는 대신 시간에 걸쳐 요청을 더 균등하게 분산하세요.
Implement caching
  • 드물게 변경되는 자주 액세스되는 데이터를 캐시하세요.
  • OAuth2 액세스 토큰을 전체 1시간 TTL 동안 사용하세요 — 요청마다 POST /oauth2/token을 호출하지 마세요.
  • 적절한 캐시 무효화 전략을 구현하세요.
Use webhooks instead of polling

GET /client/v1/process/\{id\} 폴링 대신 PROCESS_STATE_FINISHED에 대한 웹훅 및 이벤트를 구독하세요. 폴링 루프는 높은 트래픽에서 GET 프로세스 예산을 쉽게 소진할 수 있습니다.

한도에 도달했을 때 발생하는 일​

플랫폼은 다음을 반환합니다:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
헤더의미
Retry-After재시도 전 대기할 초 단위 시간. 이를 준수하세요.

Retry-After가 없으면 지수 백오프(1s, 2s, 4s, 8s, …)로 최대 60초까지 대체하세요.

동시성 고려 사항​

속도 제한은 분당 요청을 제한하지만, 플랫폼에는 인프라 수준에서 동시성 제한도 있습니다. 분당 100개의 요청 예산이 있더라도, 같은 초에 100개 모두를 발사하면 분 전체에 분산하는 것보다 거부될 가능성이 높습니다.

고처리량 통합의 경우, 버스트보다는 안정적인 RPS를 목표로 하세요.

Trully는 Webhook V2에 대한 자체 전달 할당량을 가집니다. 웹훅 서버는 1분 내에 응답해야 하며, 응답이 느린 경우 삭제됩니다(사용자의 프로세스에는 영향을 미치지 않음). 일관된 처리를 위해 웹훅을 빠르게 승인하고 비동기적으로 처리하세요.

다음 단계​

마지막 업데이트 에