Rate Limits

Halfbill applies rate limits to ensure fair usage and protect platform stability. Limits are evaluated in a few independent layers:

• Per-organization endpoint limits — a requests-per-minute cap on every API endpoint, scoped to your organization.
• Upstream limits — limits enforced per model by the model vendor when applicable.

Per-Organization Endpoint Limits

Every API endpoint is rate limited per organization using a rolling 60-second window. The limit is independent for each endpoint, so traffic to /v1/chat/completions does not consume the budget for /v1/messages.

The default limits (requests per minute, per organization) are:

Trust Tiers (account age or spend)

For regular (pay-as-you-go) organizations, limits scale with a trust tier. An organization qualifies for a tier when its account is old enough, or when its lifetime usage spend is high enough and the account meets the tier's minimum age. The tier raises the per-endpoint RPM limits, the concurrent-request ceiling, and the daily/monthly USD spend caps below.

Spend alone never promotes a brand-new account: each spend-qualified tier also requires the minimum account age shown, so the fastest possible path to Tier 4 is 14 days — no amount of day-one usage unlocks higher limits.

For example, an org past 30 days old (or with $100+ of usage) is Tier 2: chat completions rises from 600 to 2,400 RPM, with a $500/day and $5,000/month spend ceiling.

Qualifying spend counts usage billed to your credit balance only and is net of refunds: every refunded payment is deducted, so refunded or clawed-back money never raises limits. Refunded top-ups still count against the top-up allowance below — refunding does not free up top-up headroom.

Daily & Monthly Spend Caps

Regular organizations also have hard USD spend ceilings — a daily and a monthly cap set by the trust tier above — so a brand-new account has a tight dollar velocity limit that rises as it ages or spends. Code and Chat plan orgs have their own plan limits instead. When a cap is reached, requests return 429 until the counter resets (UTC midnight for daily, first of the month for monthly).

Top-Up Limits

Credit top-ups are also velocity-limited by trust tier: each organization can add at most a tier-scaled gross USD amount to its balance per rolling 24-hour window. This applies before any charge is made — a top-up attempt over the allowance is rejected with 429 and no card is charged.

The limit covers dashboard top-ups (card and hosted checkout), auto top-up, and Code plan pay-as-you-go top-ups. Your current allowance and usage are shown on the Settings → Limits page. Hosted checkout links expire after 30 minutes. Need a higher allowance? Email support@halfbill.uk.

Code and Chat Plans

Organizations on a Code plan (Halfbill Code) or a Chat plan have their own, tighter per-endpoint limits and do not receive the spend-based multiplier.

Code plans are inference-only and cover chat completions, messages, responses, and the models list, each at a flat 120 requests-per-minute floor.

Concurrent Request Limits

Separately from the per-minute request limits above, each organization has one budget of concurrent in-flight requests across all inference endpoints (chat completions, messages, and responses). A slot is held for a request's full lifetime — including the entire duration of a streamed response — and freed when the response finishes or the connection closes.

This bounds what a per-minute limit cannot: long-running requests. Six hundred requests per minute that each stream for two minutes hold 1,200 connections open; the concurrency budget is what keeps that pile-up from exhausting shared capacity.

For regular (pay-as-you-go) organizations the ceiling scales with the same trust tier that raises the per-minute limits; Code and Chat plans have a flat limit.

Requests over the limit receive a retryable 429:

HTTP/1.1 429 Too Many Requests
Retry-After: 1

{
	"error": {
		"message": "Too many concurrent requests for this organization (limit: 100). Retry shortly, or reduce request concurrency.",
		"type": "rate_limit_error",
		"code": "rate_limit_exceeded"
	}
}

Because slots free up continuously as in-flight requests complete, retrying after a short backoff typically succeeds — there is no fixed window to wait out. If you consistently hit the concurrency limit, reduce your client-side parallelism or email support@halfbill.uk about raising your ceiling.

Upstream Limits

Model vendors enforce their own upstream request limits. When an upstream limit is reached, Halfbill returns a 429 and includes provider-scoped headers (X-RateLimit-Limit-Provider, X-RateLimit-Remaining-Provider). Retry after a short backoff.

Rate Limit Headers

Successful authenticated responses carry the organization requests-per-minute (RPM) policy, remaining request quota, and reset delay only when they passed an RPM quota check. Anonymous requests and disabled or unavailable RPM limiters omit these headers on success.

RateLimit-Policy: "requests";q=600;w=60
RateLimit: "requests";r=599;t=60
RateLimit-Limit: 600
RateLimit-Remaining: 599
RateLimit-Reset: 60

RateLimit-Policy and RateLimit use the HTTP Structured Fields syntax in draft-ietf-httpapi-ratelimit-headers-11, currently an Internet-Draft. q is the quota, w the window in seconds, r the remaining quota, and t a reset delay in seconds. The request window rolls; the reset delay on an admitted request is a conservative upper bound, and quota may become available sooner.

Organization throttles return 429 with Retry-After in seconds, zero remaining quota, and a reset delay. Concurrency throttles identify the "concurrency" policy with qu="concurrent-requests" and suggest retrying after one second; capacity depends on requests finishing.

The legacy RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset fields remain available. RateLimit-Reset is a delay in seconds; X-RateLimit-Reset is a Unix timestamp. These fields also remain available as X-RateLimit-Limit and X-RateLimit-Remaining. Browser clients on allowed CORS origins can read these headers.

Other gates, such as spending limits and upstream throttles, can reject requests independently of the advertised organization quota. Honor Retry-After when supplied; otherwise use exponential backoff with jitter. Inspect the error body to distinguish a temporary throttle from a spending limit that needs account action.

Rate Limit Exceeded

When you exceed a rate limit, you'll receive a 429 Too Many Requests response:

{
	"error": {
		"message": "Rate limit exceeded for /v1/chat/completions. Please retry after 12 seconds.",
		"type": "rate_limit_error",
		"code": "rate_limit_exceeded"
	}
}

This uses the standard OpenAI-compatible error envelope. Requests to the Anthropic-compatible /v1/messages endpoint receive the Anthropic error shape instead. See Error Handling for the full format and status-code reference.

Overload (529)

Separately from per-account rate limits, Halfbill protects itself from transient overload. When a single API instance is holding too many concurrent in-flight inference requests at once — across all organizations combined (for example during a traffic spike, or when an upstream vendor is slow and connections pile up) — it sheds excess inference requests with an HTTP 529 response instead of letting them queue indefinitely. Non-inference endpoints such as the models list are unaffected:

HTTP/1.1 529
Retry-After: 1

{
	"error": {
		"message": "Gateway overloaded, please retry",
		"type": "overloaded",
		"code": "overloaded"
	}
}

Requests to the Anthropic-compatible /v1/messages endpoint receive the equivalent Anthropic envelope ({ "type": "error", "error": { "type": "overloaded_error" } }), matching Anthropic's own 529 behavior.

How 529 differs from 429:

Best Practices

• Respect Retry-After. Implement exponential backoff when you receive 429 or 529 responses, starting from the Retry-After value.
• Watch the headers. Monitor RateLimit or RateLimit-Remaining to back off before you hit the limit.
• Spread traffic across endpoints. Limits are per endpoint, so unrelated workloads don't compete for the same budget.
• Scale with usage. Regular organizations unlock higher limits automatically as lifetime spend grows. Need higher limits? Email support@halfbill.uk.