Rate Limits

Revenium applies rate limits at two layers so that one caller cannot degrade the platform for everyone: a per-API-key ceiling at the edge, applied before a request reaches the application, and per-account buckets inside the application. Both answer 429 Too Many Requests. This page describes each layer, how to tell which one refused a request, and what to do about it.

Limits are set to protect the platform and are raised on request; see Need a higher limit? below.

Last updated 25 September 2026.

Edge limit: per API key

Every request under https://api.revenium.ai/profitstream/ that carries an x-api-key header is counted per key at the edge. Metering ingest (/meter/v2/** and /v2/otlp/**) is outside this scope and does not consume the allowance.

Scope	Limit	Window	When refused
All REST API endpoints under https://api.revenium.ai/profitstream/	300 requests per API key	trailing 60 seconds	429 with Retry-After: 60

• The limit is per API key, not per account. Two keys under one account each get their own 300 requests per minute.
• Requests that carry no x-api-key header, such as the Revenium web app on a user session, are not counted at this layer.
• Nothing is banned. A key over the limit keeps receiving 429 only while its request count over the trailing 60 seconds stays above 300; once it drops back under, requests are served again with no reset on your side. Detection and release can each lag by up to about 30 seconds.
• Metering ingest (/meter/v2/** and /v2/otlp/**) is not enforced at the edge today. It is governed by the application limits below.

An edge refusal carries a Retry-After header and this body, and no X-RateLimit-* headers:

{
  "error": "rate_limited",
  "message": "This API key exceeded 300 requests in 60 seconds on the Revenium API. Retry after the Retry-After header; contact [e-mail] to raise the limit."
}

Application limits: per-account buckets

Revenium applies generous rate limits inside the application to keep usage predictable for agents and integrations. Limits are scoped per account and grouped into three buckets, each with its own ceiling and observable response headers.

Buckets and limits

Every authenticated request is mapped to one of three buckets based on the path. Each bucket has its own request-per-second limit.

Bucket	Paths	Limit
metering	/meter/v2/** (REST metering: AI completions, events, tool, API) and /v2/otlp/** (OTLP signals)	1,000 req/sec
analytics	AI Metrics, AI Traces, billing analytics, chart and cost-attribution reads	100 req/sec
platform	All other /profitstream/v2/api/** and /v2/sdk/** endpoints (CRUD on subscriptions, tenants, sources, integrations, alerts, models, anomalies, plus SDK auth endpoints)	50 req/sec

Bucket limits are per account, not per API key. If your integration uses multiple keys under the same account, they share the bucket budget.

Metering ingest additionally carries a per-key limit of 100 requests per second for each API key, reported with the same headers and metering bucket value as the account bucket. A single key cannot exceed 100 requests per second on /meter/v2/** or /v2/otlp/** even when the account bucket has budget left.

Response headers

Four headers appear on every authenticated response that resolves to a bucket, regardless of status code (2xx, 4xx, 5xx, 204).

Header	Meaning
X-RateLimit-Limit	Maximum requests allowed in the current window for this bucket
X-RateLimit-Remaining	Requests remaining in the current window. Reaches 0 at the limit, never goes negative
X-RateLimit-Reset	Unix epoch (seconds) when the current window resets
X-RateLimit-Bucket	Which bucket this request mapped to: metering, analytics, or platform

Use Remaining to throttle preemptively. Use Reset to schedule your next batch. Use Bucket so a metering call does not back off because a platform call was busy.

Limits reset each second. Use X-RateLimit-Reset to see exactly when.

When you hit the limit

A request that exceeds the bucket budget returns 429 Too Many Requests with two additional headers and a JSON body.

Additional headers:

Header	Meaning
Retry-After	Seconds to wait before retrying. Integer, always present
X-RateLimit-Limited-Reason	Why the limit fired. Values: bucket-rate (bucket exhaustion) or error-pattern (repeated 4xx responses)

Response body:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded for bucket metering. Retry after 1 second.",
    "bucket": "metering",
    "doc_url": "https://docs.revenium.io/integrations/rate-limits"
  }
}

The bucket field is present when Limited-Reason is bucket-rate. For error-pattern, the body still has type, code, message, and doc_url, but no bucket.

Error-pattern protection

Beyond per-bucket budgets, Revenium temporarily slows callers that produce sustained 4xx errors. This protects accounts from runaway misconfigured integrations spamming the API with broken requests.

Sustained 4xx over a short window triggers a temporary block. Each consecutive violation doubles the cooldown, capped at one hour. Retry-After reflects the remaining cooldown. X-RateLimit-Limited-Reason will be error-pattern.

Fix the underlying request (auth, missing fields, invalid IDs) and the cooldown clears on its own.

Which layer refused you

You see	Layer
X-RateLimit-Bucket and X-RateLimit-Limited-Reason headers, JSON body with type: rate_limit_error and a doc_url	Application bucket or error-pattern protection
Retry-After header only, JSON body with error: rate_limited	Edge per-key limit

Honor Retry-After from either layer. The edge value is always 60; the application value is the seconds left in the current window or cooldown.

Recommended client behavior

1. Read the headers. Treat X-RateLimit-Remaining and X-RateLimit-Reset as authoritative. If Remaining is low, slow down before you hit 0.
2. Honor Retry-After. On 429, wait at least that many seconds before retrying. Do not retry sooner.
3. Use exponential backoff with jitter on repeat 429s. Start at the Retry-After value and add randomized jitter to avoid thundering-herd retries with other clients in your account.
4. Differentiate by Limited-Reason:

   • bucket-rate: you are sending too fast. Throttle by Remaining.
   • error-pattern: you are sending broken requests. Fix the request shape, not the rate.
5. Separate metering from platform calls. The metering bucket has 20x the platform budget. A busy platform flow should not slow down metering.

Need a higher limit?

If you have a use case that needs sustained higher throughput, on a specific bucket or for a specific API key, contact support with the key name and the request rate you need so we can review the integration and raise the limit.