> ## 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/*`, `/api/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 |
| Notificações (in-app e push) | `/integracao/v1/notificacao/inAppMessaging`<br />`/integracao/v1/notificacao/push` | 200 \* faixa requisições por minuto |
| Padrão (`/integracao/v1`) | `/integracao/v1/*` | 200 \* faixa requisições por minuto |
| Padrão (`/api/v1`) | `/api/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 (recarga e saque) | `/api/integracao/recarregarCreditosCondutor`<br />`/api/integracao/sacarCreditosCondutor` | `condutor.identificacao` no body | 5 por minuto por condutor |
| Saldo e documentos de condutor | `/api/integracao/saldoCreditosCondutor`<br />`/api/integracao/obterDocumentosCadastroCondutor` | `condutor.identificacao` no body | 12 por minuto por condutor |
| Notificações a passageiro | `/integracao/v1/notificacao/inAppMessaging`<br />`/integracao/v1/notificacao/push` | `passageiros` no body | 4 por minuto por conjunto de passageiros |
| 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.

Nas notificações, o conjunto de passageiros informado em `passageiros` é tratado como um único recurso: o mesmo conjunto só pode receber 4 envios por minuto. Lotes com mais de 100 passageiros contam apenas no limite do grupo.

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.