BroadRouter
Get started

BroadNet Inference error codes and when to retry

Updated

Check the HTTP status before parsing the body. Retry 429 and 5xx with bounded exponential backoff. Fix 400, 403, 413 and 422 before retrying. For 401 check the key and balance, and for 402 fund the account. Always log the X-Request-ID header for support.

The API returns a normal HTTP status and a machine-readable error code. Pick the next step from the status. This table follows BroadNet’s API reference.

Status What it means What to do
400 / 422 Invalid request or field Fix the request first
401 Missing, invalid or expired key, a blocked pay-as-you-go budget, or an exhausted allowance Check the key status and account balance
402 insufficient_balance The account cannot cover a purchase; the body includes balance and price Fund the account, then try again
403 Refused by model, route or IP policy Fix the mismatch, for example an IP allow-list
409 Conflicts with account state: mint_in_progress, key_limit_reached, credential_limit_reached, key_pending Retry only mint_in_progress, with the same request_id
413 Request too large; transcription files are capped at 26,214,400 bytes Make the request smaller
429 Rate, concurrency, token-rate or spending limit reached Read the response details, back off and retry
500 / 502 / 503 / 504 Server-side processing Retry with bounded exponential backoff; reuse the same request_id for hourly key purchases

BroadNet’s docs say to check the HTTP status before you parse a JSON body, then read the machine-readable error code where there is one.

What limits cause a 429?

A pay-as-you-go key allows 30 requests a minute and 4 requests in flight at once. BroadNet’s docs give an hourly key 120 requests a minute, one stream and 300,000 tokens a minute. On an unlimited plan, each session runs one request at a time. To see how these limits compare with OpenAI, Anthropic, Groq and DeepSeek, read LLM API rate limits by provider.

How do I retry with the OpenAI SDK?

The OpenAI Python SDK already retries connection errors, 408, 409, 429 and 5xx responses twice by default, with short exponential backoff, according to its README on GitHub. Its default timeout is 10 minutes. Set both explicitly:

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
)

How do I write my own backoff?

If you call the API without an SDK, cap both the number of tries and the wait:

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

Never retry 400, 403, 413 or 422 unchanged: the same request fails the same way. Each retry of a chat request is a new inference and is billed again on pay-as-you-go. See exponential backoff for the general pattern.

Retrying an hourly key purchase safely

POST /portal/keys/hourly takes a request_id. After a timeout, a lost connection, a 409 mint_in_progress or a 5xx, retry with the same request_id. A reused request_id never creates or charges a second key; the replay returns already_issued: true and the alias. Never generate a new id until you know the first result. More on idempotency keys.

Troubleshooting

  • 401 right after a top-up. BroadNet’s account page shows the latest recorded allowance and marks a funding change as updating while it is applied. Refresh the page and try again once it has finished.
  • 429 with only a few requests a minute. You are probably hitting the 4-request concurrency limit, for example with long streams running in parallel. Use a small worker pool.
  • 403 on one model but not another. The key’s policy does not cover that model or route. Plan keys, for example, are for broadnet/deepseek-v4.1-flash, and an hourly key covers only broadnet/gemma-4-26b-a4b.
  • The SDK retried and you were billed twice. A retried chat request is a new inference. Set max_retries=0 where a duplicate answer costs more than a failed one.

What to send support

Include the X-Request-ID header value, the UTC timestamp, the route, the HTTP status and your key alias. Never send the key itself. The OpenAI Python SDK guide shows how to read the header.

Questions

Should I retry a 429 error from an LLM API?

Yes, with bounded exponential backoff. A 429 on BroadNet Inference means a rate, concurrency, token-rate or spending limit was reached. Lower your parallelism if it keeps happening, and stop retrying once a spending limit is the cause.

Why do I get 401 when my key is correct?

On BroadNet a 401 also covers an exhausted pay-as-you-go allowance or a blocked budget, not only a wrong or expired key. Check the account balance and the key status on the account page.

What is the difference between 401 and 403 here?

A 401 is about the key or the account allowance. A 403 means the key works but the request is refused by model, route or IP policy, for example a call from an address that is not on the allow-list.

Does the OpenAI SDK retry errors automatically?

Yes. The OpenAI Python SDK retries connection errors, 408, 409, 429 and 5xx twice by default with short exponential backoff. Set max_retries to change the count or 0 to turn retries off.

Read as MarkdownAsk ChatGPTAsk ClaudeAsk Perplexity