---
title: "Erros de API de LLM 401, 402, 409, 429: quando repetir"
description: "O que cada status HTTP da API da BroadNet Inference significa, quais repetir com backoff, quais corrigir antes e o que enviar ao suporte com o ID da requisição."
url: https://broadrouter.com/pt/guides/errors-and-retries/
lang: pt-BR
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traduzido do inglês com ajuda de IA. [Leia o original em inglês](https://broadrouter.com/guides/errors-and-retries/) (atualizado em 2026-11-14).

# Códigos de erro da BroadNet Inference e quando tentar de novo

Atualizado em 2026-11-14

Confira o status HTTP antes de interpretar o corpo. Tente de novo 429 e 5xx com backoff exponencial limitado. Corrija 400, 403, 413 e 422 antes de tentar de novo. Para 401, confira a chave e o saldo; para 402, recarregue a conta. Sempre registre o cabeçalho X-Request-ID para o suporte.

A API retorna um status HTTP normal e um código de erro legível por máquina. Escolha o próximo passo pelo status. Esta tabela segue a [referência da API](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-errors-and-retries&utm_content=body#errors) da BroadNet.

| Status | O que significa | O que fazer |
| --- | --- | --- |
| 400 / 422 | Requisição ou campo inválido | Corrija a requisição primeiro |
| 401 | Chave ausente, inválida ou expirada, orçamento de pagamento por uso bloqueado ou cota esgotada | Confira o status da chave e o saldo da conta |
| 402 `insufficient_balance` | A conta não cobre uma compra; o corpo traz o saldo e o preço | Recarregue a conta e tente de novo |
| 403 | Recusada pela política de modelo, de rota ou de IP | Corrija a divergência, por exemplo [uma lista de IPs permitidos](https://broadrouter.com/pt/guides/api-keys-ip-allow-lists/) |
| 409 | Conflito com o estado da conta: `mint_in_progress`, `key_limit_reached`, `credential_limit_reached`, `key_pending` | Tente de novo só `mint_in_progress`, com o mesmo `request_id` |
| 413 | Requisição grande demais; arquivos de transcrição têm limite de 26.214.400 bytes | Diminua a requisição |
| 429 | Limite de taxa, de simultaneidade, de tokens por minuto ou de gastos atingido | Leia os detalhes da resposta, espere com backoff e tente de novo |
| 500 / 502 / 503 / 504 | Processamento no servidor | Tente de novo com backoff exponencial limitado; em compras de chave por hora, reutilize o mesmo `request_id` |

A documentação da BroadNet diz para conferir o status HTTP antes de interpretar um corpo JSON e, depois, ler o código `error` legível por máquina, quando houver um.

## Quais limites causam um 429?

Uma chave de pagamento por uso permite 30 requisições por minuto e 4 requisições simultâneas. Segundo a documentação da BroadNet, uma chave por hora tem 120 requisições por minuto, um stream e 300,000 tokens por minuto. Em um [plano ilimitado](https://broadrouter.com/pt/guides/unlimited-llm-api-sessions/), cada sessão roda uma requisição por vez. Para comparar esses limites com OpenAI, Anthropic, Groq e DeepSeek, leia [limites de taxa de APIs de LLM por provedor](https://broadrouter.com/pt/blog/llm-api-rate-limits-by-provider/).

## Como tentar de novo com o SDK da OpenAI?

Segundo o [README no GitHub](https://github.com/openai/openai-python#retries), o SDK Python da OpenAI já tenta de novo, por padrão, duas vezes erros de conexão e respostas 408, 409, 429 e 5xx, com um backoff exponencial curto. O timeout padrão é de 10 minutos. Defina os dois de forma explícita (no código, os comentários dizem que 0 desliga as novas tentativas automáticas e que o timeout, em segundos, deve subir para respostas com raciocínio longo):

```python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://inference.broadnet.ai/v1",
    api_key=os.environ["BROADNET_API_KEY"],
    max_retries=4,   # 0 turns automatic retries off
    timeout=120,     # seconds; raise it for long reasoning answers
)
```

## Como escrever o meu próprio backoff?

Se você chama a API sem SDK, limite tanto o número de tentativas quanto a espera:

```python
import random, time, requests

RETRY = {429, 500, 502, 503, 504}

def post_with_backoff(url, headers, body, tries=5):
    for attempt in range(tries):
        r = requests.post(url, headers=headers, json=body, timeout=120)
        if r.status_code not in RETRY:
            return r                      # success, or an error to fix rather than retry
        time.sleep(min(30, 2 ** attempt) + random.random())
    return r
```

Nunca repita 400, 403, 413 ou 422 sem mudanças: a mesma requisição falha do mesmo jeito. Cada nova tentativa de uma requisição de chat é uma nova inferência e, no pagamento por uso, é cobrada de novo. O padrão geral está em [backoff exponencial](https://broadrouter.com/pt/glossary/exponential-backoff/).

## Como repetir com segurança a compra de uma chave por hora

`POST /portal/keys/hourly` aceita um `request_id`. Depois de um timeout, de uma conexão perdida, de um 409 `mint_in_progress` ou de um 5xx, tente de novo com o **mesmo** `request_id`. Um `request_id` reutilizado nunca cria nem cobra uma segunda chave; a repetição retorna `already_issued: true` e o alias. Nunca gere um id novo antes de saber o resultado do primeiro. Mais sobre [chaves de idempotência](https://broadrouter.com/pt/glossary/idempotency-key/).

## Solução de problemas

-   **401 logo depois de uma recarga.** A página da conta da BroadNet mostra a última cota registrada e marca uma mudança de saldo como em atualização enquanto ela é aplicada. Atualize a página e tente de novo quando terminar.
-   **429 com poucas requisições por minuto.** Provavelmente você está batendo no limite de 4 requisições simultâneas, por exemplo com streams longos rodando em paralelo. Use um pool pequeno de workers.
-   **403 em um modelo, mas não em outro.** A política da chave não cobre esse modelo ou essa rota. Chaves de plano, por exemplo, são para `broadnet/deepseek-v4.1-flash`, e uma chave por hora cobre apenas `broadnet/gemma-4-26b-a4b`.
-   **O SDK tentou de novo e você foi cobrado duas vezes.** Uma requisição de chat repetida é uma nova inferência. Defina `max_retries=0` onde uma resposta duplicada custa mais do que uma que falhou.

## O que enviar ao suporte

Inclua o valor do cabeçalho `X-Request-ID`, o horário em UTC, a rota, o status HTTP e o alias da sua chave. Nunca envie a chave em si. O [guia do SDK Python da OpenAI](https://broadrouter.com/pt/guides/openai-python-sdk/) mostra como ler o cabeçalho.

## Termos neste guia

[Rate limit (limite de taxa)](https://broadrouter.com/pt/glossary/rate-limit/)

Um rate limit é um teto que uma API impõe a quanto um cliente pode usá-la em um intervalo de tempo, como requisições por minuto ou tokens por minuto. As requisições acima do limite são recusadas, normalmente com HTTP 429 Too Many Requests, até que o uso volte a ficar abaixo dele.

[Concorrência (concurrency)](https://broadrouter.com/pt/glossary/concurrency/)

Concorrência é o número de requisições que um cliente tem em andamento ao mesmo tempo. APIs de LLM muitas vezes a limitam por chave ou por plano, separadamente das requisições por minuto, porque cada requisição aberta ocupa capacidade de GPU até a resposta terminar.

[Pagamento por uso (pay-as-you-go)](https://broadrouter.com/pt/glossary/pay-as-you-go/)

Pagamento por uso é um modelo de preço em que você paga só pelo que usa, medido por unidade, como tokens, requisições ou minutos de áudio, sem assinatura nem compromisso mínimo. A maioria das APIs de LLM cobra assim, a partir de um saldo pré-pago ou de uma fatura periódica.

[Token](https://broadrouter.com/pt/glossary/token/)

Um token é a unidade de texto que um modelo de linguagem lê e escreve: uma palavra, parte de uma palavra, um sinal de pontuação ou uma sequência de bytes gerada pelo tokenizador do modelo. As APIs de LLM contam, limitam e normalmente cobram o uso em tokens.

[Backoff exponencial (exponential backoff)](https://broadrouter.com/pt/glossary/exponential-backoff/)

Backoff exponencial é uma estratégia de retry em que o cliente espera mais tempo depois de cada tentativa que falha, normalmente dobrando o atraso até um teto, antes de tentar de novo. Adicionar um jitter aleatório a cada espera espalha os retries de muitos clientes, para que não atinjam o servidor no mesmo instante.

[Timeout de requisição (request timeout)](https://broadrouter.com/pt/glossary/request-timeout/)

Timeout de requisição é o tempo máximo que um cliente HTTP espera por um servidor antes de abandonar a requisição. Os clientes costumam dividi-lo em timeout de conexão, para abrir a conexão, e timeout de leitura, para esperar os dados. Chamadas a LLMs precisam de timeouts de leitura generosos, porque respostas longas levam tempo.

[Crédito pré-pago (prepaid credit)](https://broadrouter.com/pt/glossary/prepaid-credit/)

Crédito pré-pago é dinheiro adicionado a uma conta de API antes do uso. Cada requisição desconta o próprio custo do saldo e, quando o saldo acaba, as requisições cobradas por uso param até você fazer uma recarga. Ele limita o gasto ao que você já pagou.

[Lista de IPs permitidos (IP allow list)](https://broadrouter.com/pt/glossary/ip-allow-list/)

Uma lista de IPs permitidos é um controle de segurança que aceita requisições apenas de endereços IP ou faixas CIDR listados e recusa todos os outros. Em uma API, ela limita o estrago de uma chave vazada, porque a chave não funciona a partir de redes que não estão na lista.

## Perguntas frequentes

### Devo tentar de novo um erro 429 de uma API de LLM?

Sim, com backoff exponencial limitado. Na BroadNet Inference, um 429 significa que um limite de taxa, de simultaneidade, de tokens por minuto ou de gastos foi atingido. Se continuar acontecendo, reduza o paralelismo, e pare de tentar de novo quando a causa for um limite de gastos.

### Por que recebo 401 se a minha chave está certa?

Na BroadNet, um 401 também cobre uma cota de pagamento por uso esgotada ou um orçamento bloqueado, não só uma chave errada ou expirada. Confira o saldo da conta e o status da chave na página da conta.

### Qual é a diferença entre 401 e 403 aqui?

Um 401 tem a ver com a chave ou com a cota da conta. Um 403 significa que a chave funciona, mas a requisição foi recusada pela política de modelo, de rota ou de IP, por exemplo uma chamada de um endereço que não está na lista de IPs permitidos.

### O SDK da OpenAI tenta de novo automaticamente?

Sim. Por padrão, o SDK Python da OpenAI tenta de novo duas vezes erros de conexão, 408, 409, 429 e 5xx, com um backoff exponencial curto. Defina max\_retries para mudar a quantidade, ou 0 para desligar as novas tentativas.

## Guias relacionados

-   [Streaming de chat completions e conexões que caem](https://broadrouter.com/pt/guides/streaming-chat-completions/)
-   [Restrinja chaves de API aos seus servidores com lista de IPs](https://broadrouter.com/pt/guides/api-keys-ip-allow-lists/)
-   [Como usar o SDK Python da OpenAI com a BroadNet Inference](https://broadrouter.com/pt/guides/openai-python-sdk/)

Teste com a sua carga de trabalho real. Contas novas começam com US$ 5 de crédito para Gemma e transcrição. DeepSeek, GLM e Qwen3.8 exigem uma recarga.

[Começar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-errors-and-retries&utm_content=page-cta) ·

**Fontes**

-   [Referência da API da BroadNet Inference, erros e novas tentativas (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-errors-and-retries&utm_content=sources#errors)
-   [Referência da API da BroadNet Inference, limites (em inglês)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=pt-guides-errors-and-retries&utm_content=sources#limits)
-   [README do SDK Python da OpenAI, novas tentativas e timeouts (conferido em 2026-11-14)](https://github.com/openai/openai-python#retries)
