할당량 및 속도 제한 가이드

FedEx는 매일 수천 개의 API 요청을 받습니다. FedEx는 세 가지 스로틀링 메커니즘을 사용해 그 많은 요청을 관리합니다. 할당량, 속도 제한 및 임계값을 바탕으로 FedEx 자원을 효과적이고 효율적으로 할당합니다.

할당량은 조직 및 API 프로젝트당으로 정의됩니다.

조직당 할당량

트랜잭션 할당량은 조직에서 하루 동안 허용되는 최대 API 요청 수입니다. 따라서 API 사용자는 한 조직 내 모든 프로젝트에서 실행된 총 API 요청 수를 고려해야 합니다. FedEx API 응답에서 반환된 데이터의 양에 상관없이 각 요청은 동등하게 계산됩니다.

예: 어떠한 조직의 API 요청 하루 할당량이 500,000이라고 가정할 경우, 하루가 시작되고 처음 몇 시간 만에 조직이 500,000회의 요청을 제출하여 일일 할당량에 도달했습니다. 그러면 다음 날이 될 때까지 나머지 하루 동안 모든 요청에 대해 “429 – 너무 많은 요청: 일일 트랜잭션 할당량을 초과했습니다. 12:00AM GMT 이후 다시 시도하십시오”라는 오류 코드가 반환됩니다.

API 프로젝트당 할당량

이 할당량은 프로젝트와 기능의 두 가지 측면에 적용됩니다.

기능이란 무엇인가요?

각 API는 제공하는 기능에 따라 그룹화됩니다. 각 기능 그룹은 하나 이상의 엔드포인트 번들입니다. 예를 들어, 배송 조회 API 기능에는 6개의 API 엔드포인트가 있는 반면에 주소 유효성 확인 기능에는 하나의 API 엔드포인트만 있습니다.

배송 조회 기능을 위한 PCPP(프로젝트당 기능당 기본 설정) 할당량 제한은 하루당 요청 10만 개입니다. 즉, 조직 내 프로젝트에서 배송 조회 기능에 있는 6개 엔드포인트로 전송되는 트래픽이 이 제한을 초과하면 하루가 끝날 때까지 "429 '너무 많은 요청'"이라는 오류가 전송됩니다. 이는 6개 엔드포인트에 대한 모든 후속 배송 조회 요청에 적용됩니다.

예: 한 프로젝트가 배송 조회 기능당 10만 개의 제한이 있는 경우(6개의 엔드포인트) 6개의 엔드포인트 모두에 대한 총 트랜잭션 수가 10만 개 제한으로 계산됩니다. 프로젝트가 해당 한도를 초과하는 경우 후속 배송 조회 트랜잭션에 대해 나머지 하루 동안 "429 - 너무 많은 요청: 일일 트랜잭션 할당량을 초과했습니다."라는 오류 코드가 반환됩니다.

속도 제한

각 프로젝트에는 10초에 1,400회 트랜잭션이라는 트랜잭션 속도 제한이 있습니다. 10초마다 트랜잭션이 이 제한을 초과하면 스로틀링 제한이 적용됩니다.

이 제한이 첫 몇 초 내에 도달하게 되면 해당 10초 중 남은 시간에 보낸 모든 트랜잭션은 스로틀링에 걸립니다. 이 스로틀링 시간 동안 “429 – 너무 많은 요청”이라는 오류 코드가 반환됩니다.

FedEx에서 첫 2초 내에 1,400회의 요청을 수신하면 이어지는 모든 트랜잭션이 다음 8초 동안 스로틀링에 걸리고 “429 – 너무 많은 요청 – 짧은 시간 동안 너무 많은 요청을 수신했습니다. 잠시 기다렸다가 다시 시도하십시오”라는 오류 메시지가 반환됩니다.

10초가 경과한 후 스로틀링 제한이 해제되고 다음 10초에 걸쳐 또 다른 카운터가 요청 수를 추적하기 시작합니다.

임계값

탄력적인 FedEx API 승인 프로세스를 위해 IP 주소 수준에서 임계값을 설정할 수 있습니다. 이 메커니즘은 인증 토큰 생성 서비스에만 적용됩니다. 두 가지 유형의 임계값이 있습니다.

1. 최대 임계값: 5초 동안 지속적으로 초당 3회
2. 평균 임계값: 2분 동안 지속적으로 초당 1회

• 퍼블릭 IP 주소가 이 임계값 제한 중 어느 것이라도 위반하면, 10분 동안 페널티를 받고 이후 10분의 시간 동안 모든 추가 요청에 대해 “403 Forbidden” 상태 코드를 받게 됩니다.
• 이 페널티 시간 동안 API 사용자가 임계값 제한 중 어느 것이라도 계속 위반하는 경우에는 페널티 시간이 연장됩니다. API 사용자가 다음 10분 동안 임계값 제한을 위반하지 않으면 페널티 시간이 종료됩니다.
• 임계값 메커니즘은 사용자의 퍼블릭 IP 주소를 기반으로 합니다. 사용자가 하나의 퍼블릭 IP에 10개의 가상 머신 인스턴스를 설치한 경우에는 해당 IP 주소에서 온 모든 요청이 임계값 제한에 대해 계산됩니다.

트래픽 관리

다음 세 가지 메커니즘은 각각 별도의 트래픽 관리 상황에 대응합니다.

• 할당량이 조직 수준에 적용됩니다. 조직 내 모든 API로부터 생성된 총 트래픽이 트랜잭션 할당량에 적용됩니다.

• 할당량이 프로젝트 수준에 적용됩니다. 프로젝트 내 하나의 API 기능으로부터 생성된 총 트래픽이 트랜잭션 할당량에 적용됩니다.

• 속도 제한이 프로젝트 수준에 적용됩니다. 프로젝트 내 모든 API로부터 생성된 총 트래픽이 속도 제한에 적용됩니다.

• IP 주소 수준에서 한도가 적용됩니다.

참고: FedEx는 오남용을 방지하기 위해 상기 언급한 스로틀링 메커니즘의 한도를 낮추도록 조치할 수 있습니다. FedEx는 API 사용자의 공평한 액세스를 유지하고 FedEx 리소스를 효과적이고 효율적으로 할당하기 위해 사전 공지 없이 할당량을 변경할 권리를 보유합니다.

FAQ

조직 내 여러 프로젝트에서 수행한 API 트랜잭션이 전부 할당량에 반영됩니까?
할당량은 조직 수준에서 적용됩니다. 한 조직에는 하나 이상의 프로젝트가 있을 수 있습니다. 그리고 각 프로젝트 하에서 하나 이상의 API를 사용할 수도 있습니다. 그 결과 동일한 조직 내 여러 프로젝트의 모든 API에서 생성된 총 트래픽이 일일 할당량으로 계산됩니다.

할당량 위반 및 속도 제한 위반 양쪽 모두에 대해 429 오류가 동일하게 반환되는 경우, 정확히 어떤 제한을 위반했는지 어떻게 식별할 수 있습니까?
오류 메시지를 읽고 유형을 구분할 수 있습니다.

임계값 제한 위반을 해결하는 방법은 무엇인가요?
OAuth 토큰은 1시간 동안 유효합니다. API 사용자는 이전 토큰이 만료될 때까지 1시간 동안 이 토큰을 충분히 활용한 다음 새 토큰을 요청하는 것이 좋습니다.

임계값 제한을 초과한 경우의 예로는 무엇이 있나요?
최대 임계값 및 평균 임계값에 대해 각각 5초 및 2분의 관찰 시간 범위가 적용됩니다. 해당 기간 동안 IP 주소에서 임계값 위반이 하나라도 발생할 경우 임계값 페널티가 부과됩니다.

예: 한 IP 주소에서 2초 동안 초당 3회의 요청이 있었다가 이후에는 요청 속도가 초당 3회 아래로 떨어지는 경우에는 최대 임계값을 위반하지 않는 것입니다. 하지만 한 IP 주소에서 5초 동안 계속해서 초당 3회의 요청이 있었다가 이후에는 5초 동안 15회 요청을 하면 5초 동안 14회의 요청을 받는 최대 임계값을 위반하는 것입니다.