Copy page

Guides

Rate limits & caps

Rate limits & caps

Hyphen keys are governed by a monthly USD budget — not a token or request-per-minute limit. The model is simple: spend up to your cap, then requests fail closed until the budget resets. You are never billed for overage.

How the budget works

• Each key has a monthly USD cap and a budget window of one month.
• Spend accrues across every endpoint and every model on that key — one shared pool, whether you call m2.5, m3, /v1/messages, or /v1/embeddings.
• When accrued spend reaches the cap, further requests return HTTP 429.
• At the start of the next monthly window, the counter resets to zero and requests flow again.

What a capped request looks like

Code
HTTP/1.1 429 Too Many Requests
Retry-After: 1209600
Content-Type: application/json

Code
{
  "error": {
    "message": "Budget has been exceeded! Monthly budget resets on 2026-08-01.",
    "type": "budget_exceeded",
    "code": "429"
  }
}

The reset date is stated in the message so you (and your tools) know exactly when access returns. The Retry-After header gives an approximate number of seconds until the window resets.

Need more before the reset? Add credits

Hitting the cap mid-month doesn't have to mean waiting. Credits extend a key past its monthly cap — top up in the console and requests resume immediately, without waiting for the window to roll over.

Handling 429 in code

Treat 429 as "budget exhausted until reset," not "back off and retry in a few seconds" — retrying immediately will just 429 again until the window rolls over (or you add credits).

Code
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.hyphen-solution.com/v1", api_key="sk-hy-...")

try:
    resp = client.chat.completions.create(
        model="m3",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except APIStatusError as e:
    if e.status_code == 429:
        # Budget spent — surface the reset date from the error message.
        print("Hyphen budget exceeded:", e.response.json()["error"]["message"])
    else:
        raise

Tips to stay under cap

• Route high-volume, low-stakes calls to m2.5 (fast/cheap).
• Reserve m3 for the hardest tasks; m2.7 is a cheaper balanced default for everyday work.
• Watch your spend in the console before the window resets, and add credits if you'll run long.

Related

• Quickstart — the first request and the cap behavior.
• Models — picking a model by tier.
• API Reference — the 429 response is documented on every endpoint.