Guide

Handle rate limits

Lumin meters per month, not per second. The challenge is knowing where the meter stands before you start a 25 to 40 call reading, not throttling burst traffic.

What gets metered

Only tools/call consumes allowance. Protocol traffic, initialize, tools/list, notifications, is never counted or blocked.
Only successful tool calls count. Failed calls (4xx, 5xx, validation errors) are free.
The allowance refreshes on the 1st of each month, UTC.
The meter is per credential: per signed-in account on OAuth, per key on API key access.

Read the headers, not the error

Every MCP response carries X-RateLimit-Limit and X-RateLimit-Remaining. Read X-RateLimit-Remaining as you go and you will never be surprised by a 429 mid-reading.

A complete reading uses 25 to 40 calls. If you start one and hit the limit at call 30, you have spent 30 calls on an answer you cannot finish. Pre-flight the budget instead: if fewer than 50 calls remain, warn the user before you begin.

Handling a 429

When the allowance is used up, tools/call returns HTTP 429 with a JSON-RPC error, code -32000. The useful fields are in error.data:

json

{
  "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"
    }
  }
}

Do not treat this like a burst limit. retryAfterSeconds (also sent as the Retry-After header) points at the monthly refresh, so it can be days away. Sleeping and retrying is the wrong shape entirely. The right handling is to stop the current reading, tell the user when the allowance refreshes using resetAt, and point at a call pack if they need more before then.

Server-side compaction

Lumin compacts large tool responses on the server before returning them. This reduces token cost on your end but does not affect the meter. One logical tool call still counts as one.

PreviousAPI key vs OAuth NextStream responses