Skip to main content
O gateway aplica rate limit por janela deslizante de 60 segundos. Quando a requisição excede o limite de bloqueio, a API retorna 429. Os limites são aplicados por api-key. A avaliação segue a prioridade das regras: grupos específicos são avaliados antes dos prefixos mais genéricos (/integracao/v1/* e /api/integracao/*). O limite é contado por grupo de endpoints, e não por endpoint isolado: todas as chamadas às rotas de um mesmo grupo somam no mesmo contador. Por exemplo, chamar /api/integracao/solicitacao e /api/integracao/solicitacaoStatus com a mesma chave em menos de um minuto consome 2 requisições do grupo “Crítico”, e não 1 de cada endpoint. Os valores da tabela são limites base. O limite efetivo de cada grupo é o limite base multiplicado pela faixa da central. A faixa é um multiplicador inteiro, a partir de 1, definido para cada central. Por isso, na coluna Limite, os valores aparecem como limite base * faixa. Quando a central não possui faixa definida, vale a faixa 1.

​
Limites por recurso

Alguns endpoints têm, além do limite do grupo, um limite por recurso informado na requisição: a mesma api-key só pode operar o mesmo recurso, identificado na requisição, um número fixo de vezes por minuto. Esses limites são fixos e não são multiplicados pela faixa. A solicitação é identificada pelo id_mch (ou id) informado na requisição. Em /api/integracao/solicitacao, quando a requisição tem body, o identificador é lido do body e a query string é ignorada; sem body, é lido da query string. Em /api/integracao/solicitacaoStatus, é lido do id_mch da query string. Requisições sem identificador (por exemplo, listagens por filtro) contam apenas no limite do grupo. Os limites valem ao mesmo tempo: exceder qualquer um deles retorna 429. O contador por recurso é separado para cada api-key, então o consumo de um integrador não afeta o de outro.

​
Headers de rate limit

Nas respostas dos endpoints com limite de bloqueio configurado, o gateway informa o consumo da janela atual. Use esses headers para se auto-regular antes de receber 429. Quando mais de um limite de bloqueio se aplica à requisição (por exemplo, o do grupo e um limite por recurso), os headers refletem o mais restritivo (o de menor saldo). Não existe header de reset: como a contagem usa janela deslizante, não há um instante único de zeragem do contador. Na resposta 429, o tempo de espera continua sendo indicado pelo header Retry-After, em segundos.