La API devuelve un código de estado HTTP normal y un código de error legible por máquina. Elija el siguiente paso según el código de estado. Esta tabla sigue la referencia de la API de BroadNet.
| Estado | Qué significa | Qué hacer |
|---|---|---|
| 400 / 422 | Solicitud o campo no válido | Corrija primero la solicitud |
| 401 | Clave ausente, no válida o vencida, presupuesto de pago por uso bloqueado o asignación agotada | Revise el estado de la clave y el saldo de la cuenta |
402 insufficient_balance |
La cuenta no puede cubrir una compra; el cuerpo incluye el saldo y el precio | Agregue fondos a la cuenta y vuelva a intentar |
| 403 | Rechazada por una política de modelo, ruta o IP | Corrija la discrepancia, por ejemplo una lista de IP permitidas |
| 409 | Conflicto con el estado de la cuenta: mint_in_progress, key_limit_reached, credential_limit_reached, key_pending |
Reintente solo mint_in_progress, con el mismo request_id |
| 413 | Solicitud demasiado grande; los archivos de transcripción tienen un máximo de 26,214,400 bytes | Reduzca la solicitud |
| 429 | Se alcanzó un límite de frecuencia, concurrencia, tokens por minuto o gasto | Lea los detalles de la respuesta, aplique backoff y reintente |
| 500 / 502 / 503 / 504 | Procesamiento del lado del servidor | Reintente con backoff exponencial acotado; reutilice el mismo request_id en las compras de claves por hora |
La documentación de BroadNet indica revisar el código de estado HTTP antes de procesar un cuerpo JSON, y luego leer el código error legible por máquina cuando exista.
¿Qué límites provocan un 429?
Una clave de pago por uso permite 30 solicitudes por minuto y 4 solicitudes en curso al mismo tiempo. La documentación de BroadNet asigna a una clave por hora 120 solicitudes por minuto, un stream y 300,000 tokens por minuto. En un plan ilimitado, cada sesión ejecuta una solicitud a la vez. Para comparar estos límites con los de OpenAI, Anthropic, Groq y DeepSeek, lea límites de frecuencia de las APIs de LLM por proveedor.
¿Cómo reintento con el SDK de OpenAI?
El SDK de OpenAI para Python ya reintenta los errores de conexión y las respuestas 408, 409, 429 y 5xx dos veces de forma predeterminada, con un backoff exponencial corto, según su README en GitHub. Su tiempo de espera predeterminado es de 10 minutos. Configure ambos valores de forma explícita:
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
)
¿Cómo escribo mi propio backoff?
Si llama a la API sin un SDK, limite tanto la cantidad de intentos como el tiempo de 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 reintente sin cambios un 400, 403, 413 o 422: la misma solicitud fallará de la misma manera. Cada reintento de una solicitud de chat es una nueva inferencia y se factura de nuevo en el pago por uso. Consulte backoff exponencial para ver el patrón general.
Reintentar de forma segura la compra de una clave por hora
POST /portal/keys/hourly recibe un request_id. Después de un tiempo de espera agotado, una conexión perdida, un 409 mint_in_progress o un 5xx, reintente con el mismo request_id. Un request_id reutilizado nunca crea ni cobra una segunda clave; la repetición devuelve already_issued: true y el alias. Nunca genere un id nuevo hasta conocer el resultado del primero. Más información sobre claves de idempotencia.
Solución de problemas
- 401 justo después de una recarga. La página de la cuenta de BroadNet muestra la última asignación registrada y marca un cambio de fondos como en actualización mientras se aplica. Actualice la página y vuelva a intentar cuando haya terminado.
- 429 con pocas solicitudes por minuto. Probablemente está alcanzando el límite de concurrencia de 4 solicitudes, por ejemplo con streams largos en paralelo. Use un grupo de workers pequeño.
- 403 en un modelo pero no en otro. La política de la clave no cubre ese modelo o ruta. Las claves de plan, por ejemplo, son para
broadnet/deepseek-v4.1-flash, y una clave por hora solo cubrebroadnet/gemma-4-26b-a4b. - El SDK reintentó y se le cobró dos veces. Una solicitud de chat reintentada es una nueva inferencia. Configure
max_retries=0donde una respuesta duplicada cueste más que una fallida.
Qué enviar al soporte
Incluya el valor del encabezado X-Request-ID, la marca de tiempo UTC, la ruta, el código de estado HTTP y el alias de su clave. Nunca envíe la clave. La guía del SDK de OpenAI para Python muestra cómo leer el encabezado.
