> ## Documentation Index
> Fetch the complete documentation index at: https://docs.machine.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limit

> Limites de requisições por minuto da API e headers de controle.

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`.

| Grupo | Paths | Limite |
| - | - | - |
| Crítico | `/api/integracao/solicitacao`<br />`/api/integracao/solicitacaoStatus` | 1900 \* faixa requisições por minuto |
| Condutores e créditos | `/api/integracao/saldoCreditosCondutor`<br />`/api/integracao/saldoCreditosCondutor/`<br />`/api/integracao/condutor`<br />`/api/integracao/taxista` | 1300 \* faixa requisições por minuto |
| Posição do condutor | `/api/integracao/posicaoCondutor` | 1000 \* faixa requisições por minuto |
| Categorias | `/integracao/v1/categoria*` | 200 \* faixa requisições por minuto |
| Bandeiras | `/integracao/v1/bandeira*` | 200 \* faixa requisições por minuto |
| Saque automático | `/integracao/v1/saqueAutomatico*` | 50 \* faixa requisições por minuto |
| Programadas | `/api/integracao/consultarProgramada` | 200 \* faixa requisições por minuto |
| Dinâmica | `/integracao/v1/dinamica*` | 200 \* faixa requisições por minuto |
| Padrão (`/integracao/v1`) | `/integracao/v1/*` | 200 \* faixa requisições por minuto |
| Padrão | `/api/integracao/*` | 1000 \* faixa requisições por minuto |

## 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.

| Recurso | Paths | Identificador | Limite |
| - | - | - | - |
| Solicitação | `/api/integracao/solicitacao`<br />`/api/integracao/solicitacaoStatus` | `id_mch` (ou `id`) | 3 por minuto por solicitação |
| Créditos de condutor e empresa (recarga e saque) | `/api/integracao/recarregarCreditosCondutor`<br />`/api/integracao/sacarCreditosCondutor`<br />`/api/integracao/recarregarCreditosEmpresa`<br />`/api/integracao/sacarCreditosEmpresa` | `condutor.identificacao` ou `empresa.identificacao` no body | 5 por minuto por condutor ou empresa |
| Saldo e documentos de condutor e empresa | `/api/integracao/saldoCreditosCondutor`<br />`/api/integracao/obterDocumentosCadastroCondutor`<br />`/api/integracao/saldoCreditosEmpresa` | `condutor.identificacao` ou `empresa.identificacao` no body | 12 por minuto por condutor ou empresa |
| Criação de cupom | `/api/integracao/criarCupom` | `gerador_cupom_id` no body | 20 por minuto por gerador |

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`.

| Header | Descrição |
| - | - |
| `X-RateLimit-Limit` | Limite efetivo do grupo na janela (limite base \* faixa). |
| `X-RateLimit-Remaining` | Requisições ainda disponíveis na janela atual. Vale `0` na resposta `429`. |
| `X-Total-Period` | Duração da janela em segundos (hoje sempre `60`). A taxa permitida é `X-RateLimit-Limit / X-Total-Period`. |

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.