Guia sobre cotas e limites de taxa

A FedEx recebe milhares de solicitações de API por dia. Ela usa três mecanismos de limitação para gerenciar esse grande volume. As cotas, os limites de taxa e os limites são usados para alocar os recursos da FedEx de modo efetivo e eficiente.

As cotas são definidas por organização e por projeto de API.

Cotas por organização

A cota de transação é o número máximo de solicitações de API de uma organização que são permitidas em um dia. Isso significa que os consumidores de API devem considerar o número total de solicitações de API para todos os projetos em uma única organização. Cada solicitação é contabilizada igualmente, seja qual for o volume de dados retornado na resposta da API da FedEx.

Exemplo: uma organização tem uma cota de 500 mil solicitações de API por dia. Se essa organização atingir 500 mil solicitações enviadas nas primeiras horas do dia, ela terá atingido a cota. Para o restante do dia, verá o código de erro “429 – Excesso de solicitações – Cota de transação diária excedida. Tente novamente depois da meia-noite (24:00 GMT)” será exibido para cada solicitação até o dia seguinte.

Cotas por projeto de API

Esta cota é aplicada em dois níveis diferentes: projeto e recurso.

O que queremos dizer com recursos?

Cada API é agrupada pelos recursos que ela oferece. Cada grupo de recursos é um pacote de um ou mais endpoints. Por exemplo, o recurso API de rastreamento tem seis endpoints de API. Já o recurso Validação de endereço tem apenas um endpoint de API.

O limite de cota padrão Por recurso/Por projeto (PCPP) referente ao recurso Rastreamento é de 100 mil solicitações por dia. Isso significa que, se o tráfego de qualquer projeto em uma organização, para qualquer um dos seis endpoints do recurso Rastreamento, exceder esse limite, enviaremos a você o erro "429 'Excesso de solicitações'" até o final do dia. Isso se aplica a todas as solicitações de rastreamento seguintes para qualquer um dos seis endpoints

Exemplo: se um projeto tem um limite de 100 mil por recurso de rastreamento (com seis endpoints), o número total de transações para todos os seis endpoints é contabilizado nesse limite de 100 mil. Se o seu projeto exceder esse limite, nas transações de rastreamento seguintes você receberá o código de erro “429 – Excesso de solicitações – Cota de transação diária excedida” pelo resto do dia (até 24:00 GMT).

Limites de taxa

Cada projeto tem um limite de taxa de 1.400 transações em um período de 10 segundos. As restrições de limitação são aplicadas se as transações excedem esse limite durante o período de 10 segundos.

Se esse limite for alcançado nos primeiros poucos segundos, qualquer transação enviada nos segundos restantes dessa janela de dez segundos será restringida. Durante esse período de restrição, um código de erro será devolvido: “429 – Excesso de solicitações”.

Se a FedEx receber 1.400 solicitações nos primeiros 2 segundos, limitaremos as transações seguintes pelos próximos 8 segundos e exibiremos a mensagem de erro “429 – Excesso de solicitações – Recebemos um excesso de solicitações em um período curto. Aguarde alguns segundos antes de tentar novamente”.

Finalizados os 10 segundos, as restrições de limitação serão suspensas e outro contador começará a rastrear o número de solicitações nos próximos 10 segundos.

Limites

As limitações são aplicadas no nível de endereço IP para tornar o processo de autorização de API da FedEx resiliente. Esse mecanismo é aplicado apenas ao serviço de geração de token de autorização. Há dois tipos de limitações:

1. Limite de intermitência: três acertos por segundo, continuamente, durante um período de cinco segundos
2. Limite médio: um acerto por segundo, continuamente, durante um período de dois minutos

• Quando um endereço IP público violar um desses limites, ele será penalizado em 10 minutos e todas as solicitações que ocorrerem durante nesse período verão o código de status “403 Proibido”.
• Se os consumidores de API continuarem violando qualquer limite durante o tempo de penalidade, esse tempo será estendido. O tempo de penalidade se encerrará se os usuários da API pararem de violar o limite pelos 10 minutos seguintes.
• Os mecanismos de limite são baseados no endereço IP público de um usuário. Se um usuário configurar dez instâncias de máquinas virtuais em um IP público, todas as solicitações desse endereço IP serão contabilizadas nesse limite.

Gerenciamento de tráfego

Cada um destes três mecanismos trata de um aspecto distinto do gerenciamento de tráfego:

• Cotas aplicadas no nível da organização: o tráfego combinado gerado por todas as APIs em uma organização está sujeito a essa cota de transação.

• Cotas aplicadas no nível do projeto: o tráfego combinado gerado para um recurso de API em um projeto está sujeito a essa cota de transação.

• Limites de taxa aplicados no nível do projeto: o tráfego combinado gerado por todas as APIs em um projeto está sujeito a esse limite de taxa.

• Os limites são aplicados no nível do endereço IP.

Observação: a FedEx pode reduzir o(s) limite(s) de qualquer um dos mecanismos de limitação mencionados acima para evitar uso indevido ou excessivo. A FedEx reserva para si o direito de alterar a alocação sem aviso prévio a fim de manter o acesso equitativo entre os consumidores de API e alocar os recursos da FedEx de modo efetivo e eficiente.

Perguntas frequentes

Todas as transações de API de uma organização provenientes de projetos diferentes são contabilizadas em relação à cota?
A cota é aplicada no nível organizacional. Em uma organização, você pode ter um ou mais projetos e, em cada projeto, uma ou mais APIs. Como resultado, o tráfego combinado gerado por todas as APIs dos diferentes projetos, todos na mesma organização, é contabilizado na cota diária.

Se o mesmo erro 429 for devolvido devido a uma violação de cota e de limite de taxa, como poderei identificar que tipo de violação eu incorri?
Você pode identificar a violação lendo a mensagem de erro.

Qual é a solução dada para uma violação de limite?
Um token OAuth é válido por uma hora. Sugerimos que os consumidores de API usem esse token durante esse tempo todo e que solicitem um novo token apenas quando o anterior expirar.

Qual seria um exemplo de quando o limite é ultrapassado?
Cinco segundos e dois minutos são janelas de observação para o limite de intermitência e o limite médio, respectivamente. Durante qualquer uma dessas janelas, se algum dos limites for violado em um endereço IP, a penalidade de limite será imposta.

Exemplo: se um endereço IP tiver três acertos por segundo em 2 segundos, seguidos de uma taxa abaixo de três acertos por segundo, o limite de intermitência não terá sido violado. Entretanto, se um endereço IP tiver três acertos por segundo continuamente por 5 segundos, seguidos de 15 acertos em 5 segundos, o limite de intermitência de 14 acertos em 5 segundos terá sido violado.