BroadRouter
Começar

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

Atualizado em

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 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
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, 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.

Como tentar de novo com o SDK da OpenAI?

Segundo o README no GitHub, 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):

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:

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.

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.

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 mostra como ler o cabeçalho.

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.

Ler em MarkdownPerguntar ao ChatGPTPerguntar ao ClaudePerguntar ao Perplexity