Rate limits e uso
Como as requisições são contabilizadas no seu plano, como é a resposta 429 e o limite de tamanho de uma única requisição.
Voltado para o futuro. O rate limiting, os limites de uso e as respostas
402, 403, 413 e 429 fazem parte do contrato da API, mas ainda não
são aplicados. Esta página descreve como eles se comportam para que você
possa construir um cliente preparado para eles. Nenhum limite numérico é
publicado aqui, porque nenhum está em vigor.
O PDF Blocks foi construído para se degradar com elegância sob carga e para manter seu uso visível. Esta página explica como o uso é contabilizado, como o rate limiting se manifesta e como dimensionar suas requisições.
Como o uso é contabilizado
O uso é contabilizado por plano e acompanhado no seu dashboard. O dashboard é a fonte da verdade sobre o que você consumiu do seu plano, tanto o número de documentos processados quanto o número de requisições feitas. Consulte-o para monitorar o consumo e ver o quanto você está perto do limite do seu plano.
Como a API é stateless, cada requisição é contabilizada por si só; não há sessões nem lotes a conciliar. Uma ação de vários documentos, como uma divisão, ainda conta como uma única requisição.
Os rate limits e a resposta 429
Quando o rate limiting for aplicado, as requisições que excederem o volume
permitido pelo seu plano serão respondidas com 429 Too Many Requests e um
corpo problem+json. Um 429 é transitório: a mesma
requisição terá sucesso assim que você reduzir o ritmo.
Construa seus clientes para lidar com isso desde o primeiro dia:
- Aumente a espera exponencialmente. Em um
429, aguarde antes de tentar de novo e aumente o intervalo a cada429seguinte (dobrando-o, por exemplo), em vez de repetir a chamada imediatamente em um laço apertado. - Respeite o
Retry-After. Quando a resposta trouxer um cabeçalhoRetry-After, aguarde pelo menos esse tempo antes de tentar de novo, em vez de usar o seu próprio intervalo. - Acrescente variação aleatória. Varie um pouco o intervalo de espera para que workers paralelos não tentem de novo em sincronia.
- Limite as tentativas. Desista depois de um número razoável de tentativas e exponha a falha, em vez de tentar para sempre.
A mesma estratégia de espera vale para o raro erro de servidor 5xx.
Limites de tamanho da requisição
Envios muito grandes podem ser rejeitados com 413 Payload Too Large. Quando
esse limite for aplicado, uma requisição cujo corpo exceder o tamanho aceito
retorna um corpo problem+json e não é processada.
Diferentemente de um 429, um 413 não terá sucesso em uma nova tentativa:
você precisa enviar um arquivo menor.
Para estratégias de envio e download em fluxo, tempos limite e processamento de documentos grandes, consulte Trabalhar com arquivos grandes.
Respostas relacionadas ao faturamento
Mais dois códigos reservados dizem respeito à sua conta, e não à requisição individual:
402 Payment Required: uma condição de faturamento ou de cota no seu plano. Resolva-a no dashboard.403 Forbidden: sua chave é válida, mas não tem permissão para usar o recurso solicitado.
Os dois aparecem no catálogo de Erros, junto com o formato completo da resposta.