---
title: "API: limites e 429 na lista de DTs (GET /dts)"
description: "Por que a lista de DTs da API (GET /dts) pode responder 429, o que cada pedido \"pesado\" significa,\n       como tratar a resposta (Retry-After, intervalo crescente) e como paginar para nunca esbarrar no limite."
---

[Pular para o conteúdo](https://ajuda.tecnovia.com.br/api-limites-e-429-na-lista-de-dts#main-content)

[Abrir um chamado de suporte](https://ajuda.tecnovia.com.br/kb-tickets/new?hsLang=pt-br)

[![logo-tecnovia-sem-fundo-2000](https://ajuda.tecnovia.com.br/hs-fs/hubfs/logo-tecnovia-sem-fundo-2000.png?width=200&height=25&name=logo-tecnovia-sem-fundo-2000.png)](https://www.tecnovia.com.br/?hsLang=pt-br)

- [Blog](https://blog.tecnovia.com.br/)
- [Ajuda](https://ajuda.tecnovia.com.br/)

Abrir navegação principal

Fechar navegação principal

- [Blog](https://blog.tecnovia.com.br/)
- [Ajuda](https://ajuda.tecnovia.com.br/)
- [Abrir um chamado de suporte](https://ajuda.tecnovia.com.br/kb-tickets/new)

 Como podemos ajudá-lo?

- Não há sugestões porque o campo de pesquisa está em branco.

1. [Central de Ajuda do Gestor Logístico](https://ajuda.tecnovia.com.br/?hsLang=pt-br)
2. [Integrações](https://ajuda.tecnovia.com.br/integra%C3%A7%C3%B5es?hsLang=pt-br)

# API: limites e 429 na lista de DTs (GET /dts)

## Por que a lista de DTs da API (GET /dts) pode responder 429, o que cada pedido "pesado" significa, como tratar a resposta (Retry-After, intervalo crescente) e como paginar para nunca esbarrar no limite.

A lista de documentos de transporte (`GET /dts`) é a consulta mais pesada da API. Para que uma chamada grande não atrase as demais — da sua empresa e dos outros usuários do sistema —, o Gestor Logístico limita quantas consultas **pesadas** rodam ao mesmo tempo. Quando todas as vagas estão ocupadas, a API responde `429` em poucos segundos, em vez de deixar a chamada esperando minutos. Este artigo mostra quais chamadas contam como pesadas, como tratar o `429` e como paginar para nem chegar perto do limite.

**Resumo:** pagine sempre (`Conf`) e informe um período; se receber `429`, espere o tempo do cabeçalho `Retry-After` e tente de novo, no máximo 1 ou 2 vezes; e não dispare exportações CSV nem filtros por situação em paralelo.

### O que é uma consulta "pesada"

Uma consulta paginada comum — com `Conf` e um período — **não** passa pelo controle e não recebe esse `429`. Contam como pesadas, e passam pelo controle, as chamadas a `GET /dts` que:

- **não informam paginação** (sem o parâmetro `Conf`);
- pedem **todos os itens de uma vez** (`TodosOsItens:true` ou `ItensPorPagina:-1`);
- filtram por **situação** (`Situacoes`);
- filtram por **período de registro de entrega** (`PeriodoRegistroEntrega`);
- filtram por **número de referência do cliente** (`NumeroRefCliente`) sem informar nenhum período;
- pedem a **exportação em CSV** (`format=csv`) — qualquer CSV é pesado.

Atenção ao primeiro item: é comum uma integração chamar `GET /dts` só com filtros, sem `Conf`. Essa chamada é tratada como pesada, mesmo que o resultado seja pequeno.

### O que o 429 significa

Significa que, naquele instante, não havia vaga para mais uma consulta pesada e a sua chamada **não foi processada**. Não é erro da sua requisição: repetir a mesma chamada daqui a pouco costuma funcionar. A resposta traz:

- status HTTP `429`;
- cabeçalho `Retry-After: 5` (segundos sugeridos para esperar);
- no corpo, `responseStatus.errorCode` igual a `SistemaOcupadoException` e uma das mensagens abaixo.

| Mensagem | Quando aparece |
| --- | --- |
| "O sistema está processando muitos pedidos pesados no momento. Por favor tente novamente em alguns segundos." | Todas as vagas de consultas pesadas estavam ocupadas e a espera curta (poucos segundos) acabou. |
| "Já existe um pedido igual a este em andamento. Aguarde o resultado." | Outra chamada **idêntica** (mesmo usuário, mesmos filtros) ainda estava em execução. A sua espera por ela é mais longa — pode levar até 2 minutos antes do `429`. |

```
HTTP/1.1 429 Too Many Requests Retry-After: 5  {   "responseStatus": {     "errorCode": "SistemaOcupadoException",     "message": "O sistema está processando muitos pedidos pesados no momento. Por favor tente novamente em alguns segundos." }}
```

### Como tratar o 429 na sua integração

- **Respeite o `Retry-After`.** Espere pelo menos esse número de segundos antes de tentar de novo.
- **Use intervalo crescente com variação aleatória (backoff com jitter).** Por exemplo: 1ª retentativa após o `Retry-After` mais 0 a 2 s aleatórios; 2ª após o dobro, também com variação. A variação evita que várias integrações tentem de novo no mesmo segundo.
- **Limite as retentativas a 1 ou 2.** Se continuar recusando, registre a falha e deixe a próxima execução agendada tentar — não insista em laço.
- **Não paralelize CSV nem consultas com `Situacoes`.** Rodar várias ao mesmo tempo só gera mais recusas; envie uma de cada vez.
- **Não repita imediatamente a mesma chamada** enquanto a anterior não terminou: o sistema reconhece pedidos idênticos e passa a recusar os repetidos.
- Trate `429` como "tentar mais tarde", e não como erro de dados: os erros de requisição (`4xx` diferentes de 429) pedem correção, não repetição.

```
tentativa = 0 enquanto tentativa <= 2:     resposta = GET /dts?...     se resposta.status != 429: parar     espera = (Retry-After ou 5) * 2^tentativa + aleatorio(0 a 2)     aguardar(espera)     tentativa = tentativa + 1 se ainda 429: registrar e tentar na próxima execução
```

### O jeito certo: paginar com Conf e informar o período

A forma de nunca esbarrar no limite é consultar por páginas e sempre dentro de um período. Isso também deixa cada chamada mais rápida. Exemplo (formato JSV na query string, o mesmo descrito em [Implementando integrações via API](https://ajuda.tecnovia.com.br/implementando-integra%C3%A7%C3%B5es-via-api?hsLang=pt-br)):

```
GET https://api15.gestorlogistico.com.br/dts?PeriodoCadastramento={Inicio:2026-10-01,Termino:2026-10-07}&Conf={ItensPorPagina:30,NumeroDaPagina:1}
```

1. Peça a página 1 e leia o `totalItens` da resposta.
2. Calcule o número de páginas (`totalItens` dividido por `ItensPorPagina`, arredondado para cima).
3. Peça as demais páginas **uma de cada vez**, trocando só `NumeroDaPagina`.
4. Prefira períodos curtos (um dia ou uma semana) e repita por intervalo, em vez de um período longo de uma vez.

Precisa filtrar por situação? Faça a consulta paginada por período e filtre a situação na sua aplicação sempre que possível; o filtro `Situacoes` é tratado como consulta pesada.

### Exportação em CSV e o limite de linhas

A exportação em CSV (`format=csv`) é sempre uma consulta pesada e tem um limite de linhas — hoje, **50.000**. Se o seu pedido resultar em mais linhas, a exportação não é gerada e a resposta traz a mensagem: *"A exportação tem \[linhas do seu pedido\] linhas e o limite é \[limite\]. Reduza o período ou refine os filtros."* A mensagem sempre informa os dois números; use o limite que ela informar, pois ele pode variar por ambiente. Reduza o período (por exemplo, uma exportação por dia) e faça uma exportação por vez. Para integração contínua, a consulta paginada em JSON é mais indicada que o CSV.

### Veja também

- [Implementando integrações via API](https://ajuda.tecnovia.com.br/implementando-integra%C3%A7%C3%B5es-via-api?hsLang=pt-br) — autenticação, formato JSV, paginação e tratamento de erros.
- [Lista de documentos de transporte (DTs): sistema ocupado e limite da exportação](https://ajuda.tecnovia.com.br/lista-de-dts-sistema-ocupado-e-limite-da-exportacao?hsLang=pt-br) — o mesmo aviso, do ponto de vista de quem usa a tela.

- [Conceitos do Gestor Logístico](https://ajuda.tecnovia.com.br/conceitos-do-gestor-log%C3%ADstico?hsLang=pt-br)
- [Novidades](https://ajuda.tecnovia.com.br/novidades?hsLang=pt-br)
- [Configurações](https://ajuda.tecnovia.com.br/configura%C3%A7%C3%B5es?hsLang=pt-br)
- [Integrações](https://ajuda.tecnovia.com.br/integra%C3%A7%C3%B5es?hsLang=pt-br)
- [Aplicativo mobile (para motoristas)](https://ajuda.tecnovia.com.br/aplicativo-mobile-para-motoristas?hsLang=pt-br)
- [Informações gerenciais](https://ajuda.tecnovia.com.br/informa%C3%A7%C3%B5es-gerenciais?hsLang=pt-br)
- [Operações de Transporte](https://ajuda.tecnovia.com.br/opera%C3%A7%C3%B5es-de-transporte?hsLang=pt-br)
- [Documentos de Transporte](https://ajuda.tecnovia.com.br/documentos-de-transporte?hsLang=pt-br)
- [Ocorrências, tracking, transit-times](https://ajuda.tecnovia.com.br/ocorr%C3%AAncias-tracking-transit-times?hsLang=pt-br)
- [Faturas das transportadoras](https://ajuda.tecnovia.com.br/faturas-das-transportadoras?hsLang=pt-br)
- [Contratos, tabelas e simulações de fretes](https://ajuda.tecnovia.com.br/contratos-tabelas-e-simula%C3%A7%C3%B5es-de-fretes?hsLang=pt-br)
- [Legislação, normas e regulamentos](https://ajuda.tecnovia.com.br/legisla%C3%A7%C3%A3o-normas-e-regulamentos?hsLang=pt-br)
- [Navegação e produtividade](https://ajuda.tecnovia.com.br/navega%C3%A7%C3%A3o-e-produtividade?hsLang=pt-br)
- [Usuários de clientes](https://ajuda.tecnovia.com.br/usu%C3%A1rios-de-clientes?hsLang=pt-br)
- [Usuários de transportadoras](https://ajuda.tecnovia.com.br/usu%C3%A1rios-de-transportadoras?hsLang=pt-br)

[![logo 125x1000](https://ajuda.tecnovia.com.br/hs-fs/hubfs/logo%20125x1000.png?width=200&height=25&name=logo%20125x1000.png "logo 125x1000")](https://tecnovia.com.br?hsLang=pt-br)

Copyright © 2025, Tecnovia Soluções para Gestão Logística