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 onlybroadnet/gemma-4-26b-a4b. - The SDK retried and you were billed twice. A retried chat request is a new inference. Set
max_retries=0where 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.
