# 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

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

```json
{
  "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.

:::tip[No surprise overage]
Because requests fail closed at the cap, a runaway agent loop can never generate
a bill beyond your monthly budget. The worst case is a `429`, not an invoice.
:::

## 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](https://app.hyphen-solution.com)
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).

```python
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](https://app.hyphen-solution.com) before the
  window resets, and add credits if you'll run long.

## Related

- [Quickstart](/quickstart) — the first request and the cap behavior.
- [Models](/models) — picking a model by tier.
- [API Reference](/api) — the `429` response is documented on every endpoint.