Limites de requisições da API da Groner

Entenda quantas chamadas sua integração pode fazer, o que acontece ao ultrapassar os limites e como evitar bloqueios.

Atualizado em 6 de outubro de 2026.

Quais são os limites?

A API da Groner aplica limites às chamadas de integrações externas para manter a disponibilidade do serviço. A contagem é feita por usuário, por conta Groner (tenant) e por grupo de métodos HTTP, em janelas de 30 minutos.

O que define o grupo é o método HTTP utilizado, e não o nome da operação. Por exemplo, uma consulta que utiliza POST consome o limite de POST.

Esses são os limites gerais. Algumas operações podem ter restrições específicas adicionais; consulte também a documentação do endpoint utilizado.

Como a contagem funciona?

• As rotas compartilham o limite do mesmo grupo. Consultar diferentes endpoints com GET não cria uma cota separada para cada um.
• Integrações que usam o mesmo usuário compartilham a contagem. Isso também vale para processos executados em computadores ou servidores diferentes.
• Os grupos são independentes. Uma chamada GET não consome a cota de POST. Já PUT e PATCH dividem a mesma cota.
• A janela começa na primeira chamada contabilizada daquele grupo. Ela expira 30 minutos depois; não é uma cota diária nem uma renovação obrigatória nos horários de relógio, como 10h e 10h30.
• Gerar um novo token não zera a contagem do usuário.

Por exemplo: se duas integrações usam o mesmo usuário e fazem, juntas, 10.000 chamadas GET dentro da janela, a próxima chamada ultrapassa o limite. Da mesma forma, 300 chamadas PUT e 200 chamadas PATCH já consomem as 500 atualizações permitidas.

O uso normal das telas da Groner tem tratamento próprio. Este artigo orienta principalmente integrações, robôs, scripts e aplicativos que acessam diretamente a API.

O que acontece ao ultrapassar o limite?

1. A chamada é recusada e o token é bloqueado

Ao exceder a cota, a API retorna HTTP 429 com o código RATE_LIMIT_BLOQUEADO. A mensagem informa o método e o limite ultrapassado.

O token utilizado fica bloqueado por 72 horas. As próximas chamadas sujeitas a essa política, feitas com esse token, recebem HTTP 401, com o código TOKEN_BLOQUEADO_EXCESSO.

A janela de 30 minutos e o bloqueio de 72 horas são coisas diferentes. Esperar a janela terminar não desbloqueia o token que já foi bloqueado.

Se o usuário continuar ativo, é possível fazer login novamente para obter um novo token. Porém, primeiro é necessário corrigir o volume de chamadas e aguardar a renovação da cota: um token novo também pode ser bloqueado se a integração continuar excedendo o limite.

2. A reincidência pode desativar o usuário

No terceiro estouro registrado dentro da janela de 7 dias, o usuário é desativado automaticamente. Os administradores ativos da conta e o próprio usuário são notificados por e-mail.

Os tokens anteriores à desativação passam a ser recusados nas chamadas sujeitas a essa política, com HTTP 403 e o código USUARIO_DESATIVADO_EXCESSO.

Para retomar o acesso:

1. Identifique e ajuste a integração que está excedendo os limites.
2. Peça a um administrador da conta para reativar o usuário na tela de usuários da Groner.
3. Faça um novo login e atualize o token utilizado pela integração.
4. Retome as chamadas respeitando as cotas.

Não é necessário ultrapassar o mesmo grupo de métodos três vezes: os estouros registrados são acumulados por usuário na mesma conta.

O que minha integração deve fazer ao receber um bloqueio?

• Interrompa as chamadas automáticas e examine o código e a mensagem retornados pela API.
• Em RATE_LIMIT_BLOQUEADO, verifique a frequência de execução, o número de processos simultâneos e outras integrações que utilizam o mesmo usuário.
• Em TOKEN_BLOQUEADO_EXCESSO, não continue reenviando o mesmo token nem crie um ciclo de login automático para insistir nas chamadas.
• Em USUARIO_DESATIVADO_EXCESSO, solicite a reativação ao administrador depois de corrigir a causa.

Outros erros 401 e 403 podem ter causas diferentes, como autenticação ou permissões. Confira sempre a mensagem e o código específico da resposta.

Como evitar atingir os limites?

1. Sincronize apenas o que mudou. Use filtros de atualização quando o endpoint oferecer esse recurso.
2. Use paginação e reutilize resultados. Evite buscar a mesma lista completa repetidamente.
3. Distribua as chamadas ao longo do tempo. Controle a concorrência e mantenha uma margem abaixo da cota para outras operações do mesmo usuário.
4. Prefira webhooks quando disponíveis. Assim, sua integração recebe eventos sem precisar consultar continuamente a API.
5. Controle as novas tentativas. Para falhas temporárias, use intervalos progressivos e um número máximo de tentativas. Para bloqueios por excesso, interrompa o fluxo e trate a causa.
6. Monitore o consumo por método. Registre a quantidade de chamadas e os retornos 429, 401 e 403 para identificar problemas antes de uma reincidência.

Precisa de ajuda?

Fale com o suporte da Groner pelo chat e informe:

• A conta e o usuário utilizados pela integração.
• O nome da integração e a operação que estava sendo executada.
• O método HTTP e o endpoint chamado.
• O horário do erro, com fuso horário.
• O status HTTP, o código e a mensagem retornados.
• O volume aproximado de chamadas no período.

Não envie senhas nem tokens de acesso. Com essas informações, o suporte consegue orientar a investigação e a retomada da integração.

Veja também

• Como mover um negócio no Groner a partir de outro sistema
• Como gerar um token de API para integrar o Groner com outros sistemas

Atualizado em: 08/10/2026