Reference

Rate limits

Lumin meters one thing: successful tools/call requests against a monthly allowance, scoped per credential. There is no daily cap and no per-second throttle to tune around.

Plan	Included	Scope
Free	300 tool calls / month	Per credential
Pay as you go	Prepaid packs from 5,000 calls, never expire	Tops up the same meter
Custom limits	By arrangement	Per-key monthly override

What counts

Only tools/call consumes allowance. Protocol traffic, initialize, tools/list, notifications, is never counted or blocked.
Only successfully executed tool calls count. A failed call, whether validation, auth, or a server fault, is free, so retry loops and pre-flight checks cost nothing.
One call is one call. No tool is weighted, and no tool is gated behind a plan: all 158 are on every plan.

Scope: per credential

On API key auth the meter is per key. On OAuth the meter is per signed-in account. Two keys owned by the same person are two meters; one account used from three clients is one meter.

Refresh

The monthly allowance refreshes on the 1st of each month at 00:00 UTC. Prepaid pack calls sit outside the refresh cycle: they never expire and are drawn down only after the monthly allowance is spent.

Headers

Every MCP response carries the current meter state, so you can watch your budget without a separate endpoint:

http

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 187

A 429 additionally carries Retry-After in seconds. Note that it points at the monthly refresh, so it can be days, not seconds. Sleeping on it is almost never the right move.

The 429 shape

When the allowance is used up, tools/call requests return HTTP 429 with a JSON-RPC error object, code -32000:

json

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": {
    "code": -32000,
    "message": "Monthly call allowance reached (300 tool calls this month). It refreshes on the 1st of the month, UTC. Need more before then? https://lumin.guru/pricing",
    "data": {
      "retryAfterSeconds": 604800,
      "limit": 300,
      "remaining": 0,
      "resetAt": "2026-08-01T00:00:00.000Z"
    }
  }
}

resetAt is the ISO timestamp of the 1st of next month, UTC. retryAfterSeconds matches the Retry-After header. The right handling is to surface the situation to your user or buy a call pack, not to queue a retry.

Custom limits

Custom limits for bigger integrations, write to contact@lumin.guru. The override is applied per key by the Lumin team, so the change is invisible to your client code: same headers, same 429 shape, a bigger number.

PreviousError codes NextEngine architecture