> ## 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 (`corridas/*` e, por fim, `/api/v2/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/v2/integracao/corridas/estimativas`, `/api/v2/integracao/corridas/programadas/estimativas` e `/api/v2/integracao/corridas/empresas` com a mesma chave em menos de um minuto consome 3 requisições do grupo "Estimativas e empresas", 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 |
| - | - | - |
| Posição de condutores livres | `/api/v2/integracao/condutores/posicoes` | 10 requisições por minuto |
| Histórico de punições de condutores | `/api/v2/integracao/condutores/historico-punicoes` | 10 requisições por minuto |
| Estimativas e empresas | `/api/v2/integracao/corridas/estimativas`
`/api/v2/integracao/corridas/programadas/estimativas`
`/api/v2/integracao/corridas/empresas/*` | 1000 \* faixa requisições por minuto |
| Créditos e documentos de condutores | `/api/v2/integracao/condutores/creditos/recargas`
`/api/v2/integracao/condutores/creditos/saques`
`/api/v2/integracao/condutores/documentos`
`/api/v2/integracao/condutores/requisitos-cadastro/documentos`
`/api/v2/integracao/condutores/areas-bloqueio/batch` | 1000 \* faixa requisições por minuto |
| Condutores | `/api/v2/integracao/condutores`
`/api/v2/integracao/condutores/*` | 750 \* faixa requisições por minuto |
| Programadas | `/api/v2/integracao/corridas/programadas`
`/api/v2/integracao/corridas/programadas/*` | 200 \* faixa requisições por minuto |
| Crítico | `/api/v2/integracao/corridas`
`/api/v2/integracao/corridas/*` | 800 \* faixa requisições por minuto |
| Categorias | `/api/v2/integracao/configuracoes/categorias/*` | 200 \* faixa requisições por minuto |
| Configurações (bandeira) | `/api/v2/integracao/configuracoes` | 200 \* faixa requisições por minuto |
| Saque automático | `/api/v2/integracao/configuracoes/saque-automatico/ativacao` | 50 \* faixa requisições por minuto |
| Dinâmica | `/api/v2/integracao/dinamicas*` | 200 \* faixa requisições por minuto |
| Notificações (in-app e push) | `/api/v2/integracao/notificacoes/in-app-messaging`
`/api/v2/integracao/notificacoes/push` | 230 \* faixa requisições por minuto |
| In-app messaging (individual) | `/api/v2/integracao/notificacoes/in-app-messaging/individual` | 900 \* faixa requisições por minuto |
| Push (individual) | `/api/v2/integracao/notificacoes/push/individual` | 1100 \* faixa requisições por minuto |
| Notificações de condutor (in-app e push) | `/api/v2/integracao/notificacoes/condutor/in-app-messaging`
`/api/v2/integracao/notificacoes/condutor/push` | 100 \* faixa requisições por minuto |
| In-app messaging de condutor (individual) | `/api/v2/integracao/notificacoes/condutor/in-app-messaging/individual` | 200 \* faixa requisições por minuto |
| Push de condutor (individual) | `/api/v2/integracao/notificacoes/condutor/push/individual` | 200 \* faixa requisições por minuto |
| Cupons | `/api/v2/integracao/cupons` | 60 \* faixa requisições por minuto |
| Cupons em lote | `/api/v2/integracao/cupons/lote` | 20 \* faixa requisições por minuto |
| Extrato de créditos | `/api/v2/integracao/financeiro/extrato` | 40 requisições por minuto |
| Criação de áreas | `/api/v2/integracao/configuracoes/areas` | 200 \* faixa requisições por minuto |
| Webhooks | `/api/v2/integracao/webhooks`
`/api/v2/integracao/webhooks/*` | 60 \* faixa requisições por minuto |
| Mensagens da corrida (envio) | `/api/v2/integracao/mensagens/corridas/passageiro`
`/api/v2/integracao/mensagens/corridas/condutor` | 900 \* faixa requisições por minuto |
| Padrão | `/api/v2/integracao/*` | 1000 \* faixa requisições por minuto |
O limite de mensagens da corrida vale para o envio; a leitura (`/api/v2/integracao/mensagens/corridas/passageiro/*` e `/api/v2/integracao/mensagens/corridas/condutor/*`) segue o limite Padrão.
## 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 |
| - | - | - | - |
| Créditos de condutor (recarga e saque) | `/api/v2/integracao/condutores/creditos/recargas`
`/api/v2/integracao/condutores/creditos/saques` | `condutor.identificacao` no body | 5 por minuto por condutor |
| Saldo e documentos de condutor | `/api/v2/integracao/condutores/creditos/saldo`
`/api/v2/integracao/condutores/documentos`
`/api/v2/integracao/condutores/requisitos-cadastro/documentos` | `identificacao` na query string | 12 por minuto por condutor |
| Notificações a passageiro | `/api/v2/integracao/notificacoes/in-app-messaging`
`/api/v2/integracao/notificacoes/push`
`/api/v2/integracao/notificacoes/in-app-messaging/individual`
`/api/v2/integracao/notificacoes/push/individual` | `passageiros` ou `passageiro_id` no body | 4 por minuto por passageiro ou conjunto de passageiros |
| Criação de cupom | `/api/v2/integracao/cupons` | `gerador_cupom_id` no body (`POST`) | 20 por minuto por gerador |
| Mensagem na corrida | `/api/v2/integracao/mensagens/corridas/passageiro`
`/api/v2/integracao/mensagens/corridas/condutor` | `solicitacao_id` no body (`POST`) | 30 por minuto por corrida |
Nas notificações, o envio individual conta por `passageiro_id`, e no envio em lote 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.
A criação de cupons em lote (`/api/v2/integracao/cupons/lote`) não entra no limite por gerador: cada requisição conta uma vez no grupo "Cupons em lote", qualquer que seja a quantidade de cupons e de geradores do lote.
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.