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 apenasbroadnet/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=0onde 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.
