Copy page

Guides

Rate limits & caps

Hyphen keys are governed primarily by a budget. A subscription key has a monthly cap that resets each cycle; a credit key has a prepaid balance that never resets or expires. The model is simple: spend up to the budget, then requests fail closed. You are never billed for overage. On top of the budget, every key carries fair-use rate limits (see below).

Fair-use rate limits

Every key also carries requests-per-minute and tokens-per-minute limits that scale with your plan. They exist so one very busy agent can't degrade the gateway for other keys. The exact values are operational and may be tuned over time. Hitting a fair-use limit returns an HTTP 429 you can retry after a short backoff — unlike the budget 429, which lasts until your allowance refreshes or you top up credit.

How the budget works

• Each subscription key has a monthly 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 minimax-m2.5, minimax-m3, /v1/chat/completions, or /v1/messages.
• Spend is metered per token at the public per-model rates — see the rate card. Standard M-series models are $0.30 / 1M input and $1.20 / 1M output; highspeed variants are exactly 2x that; minimax-text-01 is $0.20 / $1.10. Allowance dollars and credit dollars buy the same tokens at the same rates, and the usage field in every response shows exactly what was billed.
• 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? Use your credit key

Hitting the cap mid-month doesn't have to mean waiting. Prepaid credit funds a separate pay-as-you-go key with its own non-resetting balance — it doesn't raise a subscription key's cap. Buy a credit pack in the console, then point your agent at the credit key — one env-var change:

Code
# Swap the capped subscription key for your credit key
export HYPHEN_API_KEY="sk-...your-credit-key..."

You're running again on prepaid balance; your subscription key comes back on its own when the monthly window resets.

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 switch to your credit key).

Code
from openai import OpenAI, APIStatusError

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

try:
    resp = client.chat.completions.create(
        model="minimax-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

• Know the rate card: all standard M-series models meter at the same per-token rate, so minimax-m2.5 vs minimax-m3 is a speed-vs-quality call, not a cost one. The two things that actually cost more are highspeed variants (2x) and tokens themselves — trim context and output length before switching models.
• Avoid -highspeed models for background or batch calls — you pay double per token for latency you don't need.
• Check your spend in the console before the window resets, and buy a credit pack 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.