Rate Limits

API rate limiting and best practices for high-volume usage submission.

Rate limiting is not yet enforced. The limits below describe the planned configuration.

Planned limits

Scope	Limit
Per API key	100 requests/minute
Usage events per request	100 events (enforced now)

Best practices

Batch your events

Submit up to 100 events per request instead of one-at-a-time. This is both faster and more efficient:

{
  "events": [
    { "event_id": "evt-001", "metric": "revenue_amount_invoiced", "quantity": 5000, ... },
    { "event_id": "evt-002", "metric": "revenue_amount_invoiced", "quantity": 8000, ... },
    { "event_id": "evt-003", "metric": "revenue_amount_invoiced", "quantity": 3000, ... }
  ]
}

Aggregate when possible

If your system generates many small events, consider aggregating them before submission. For example, sum all transactions in an hour and submit one event per hour instead of one per transaction.

Handle 429 responses

When rate limiting is enabled, exceeding the limit will return HTTP 429. Back off and retry:

if (res.status === 429) {
  const retryAfter = parseInt(res.headers.get("Retry-After") ?? "60", 10);
  await new Promise((r) => setTimeout(r, retryAfter * 1000));
}