Limits and headers

Limits are set per key by the pump.fun team. Every key starts at the defaults below; ask support to raise them.

The two limits

Limit	Default	How it is measured
Rate (burst window)	1 request per second	A sustained rate with a 60 second bucket: the bucket holds 60 × the per-second rate, refills continuously, and a request is refused when the bucket is empty. At the default you can send 60 requests at once and then 1 per second.
Daily (day window)	50,000 requests	A counter per UTC day across all routes. Resets at 00:00 UTC.

The two limits count differently:

• The rate bucket is debited by every request that passes the key and scope checks, whatever the route then answers. Requests refused for a missing or invalid key, or for a missing scope, do not touch it.
• The daily counter counts only requests the API answered successfully (2xx or 304). A slot is reserved before the route runs and handed back when the response is anything else (a 4xx, a 5xx or a dropped connection), so refused or failed calls do not spend your daily budget.

The MCP server makes exactly one API request per tool call, so its calls count the same way.

A key whose rate or daily limit has been set to 0 is paused: it answers 429 on every request with Retry-After: 60 and the message This key is paused; contact support, without touching the limiter.

Response headers

Every response to a request whose key was recognised carries these headers, set by the API itself. (A 401 for a missing or unknown key carries X-Request-Id only.)

Header	Meaning
X-RateLimit-Limit	Size of the 60 second bucket (60 × the key’s per-second rate).
X-RateLimit-Remaining	The smaller of the requests left in the bucket and the requests left in today’s daily limit. When the daily limit is the tighter one, this number counts down towards it.
X-RateLimit-Reset	Unix time in seconds at which the ceiling that X-RateLimit-Remaining reports moves: when the bucket is full again, or 00:00 UTC when the daily limit is the tighter one (and on a day 429).
Retry-After	Seconds to wait. Present on 429 and 503 only.
X-Request-Id	Request id generated by the API (a UUID). Quote it in support requests. Any X-Request-Id you send is ignored.
x-pump-api-key-id	Opaque id of the key that made the request (a UUID, never the key itself). Also useful in support requests.
Cache-Control	Always no-store: keyed responses are never cacheable by intermediaries.

Deprecated routes add Deprecation, Sunset and Link; see Versioning and deprecation.

Worked example

A key at the default rate has just made its second call of the minute. The bucket holds 60, 58 are left, and it will be full again at the Unix second in X-RateLimit-Reset:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Cache-Control: no-store
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1767225660
X-Request-Id: 7d1f0a2e-5b8c-4b1e-9a7f-2c3d4e5f6a7b
x-pump-api-key-id: 3f9c2b1a-4d5e-4f60-8a7b-9c0d1e2f3a4b

Sixty more calls in the same second empty the bucket; the sixty-first is refused and tells you how long to wait:

HTTP/1.1 429 Too Many Requests
Retry-After: 1
Cache-Control: no-store
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1767225661

429 Too Many Requests

A refused request answers 429 with Retry-After and this body:

{
  "statusCode": 429,
  "timestamp": "2026-01-01T00:00:00.000Z",
  "path": "/v1/users/123",
  "error": "API_KEY_RATE_LIMITED",
  "message": "Rate limit of 60 requests per minute exceeded",
  "retryAfterMs": 1000,
  "limit": 60,
  "window": "burst"
}

window tells you which limit was hit:

window	Meaning	What to do
burst	The 60 second bucket is empty.	Wait retryAfterMs (usually under a second at the default rate).
day	The UTC-day counter reached the daily limit. The message reads Daily limit of 50000 requests reached; resets at 00:00 UTC and X-RateLimit-Reset points at that midnight.	Wait until 00:00 UTC (Retry-After says how long), or ask for a higher daily limit.
auth	Too many failed keys from your IP address (60 per 10 minutes). Only unknown, malformed, revoked, suspended or not-yet-approved keys count.	Fix the key you are sending; valid keys are never throttled this way.
lookup	Too many uncached key lookups from your IP address (600 per 10 minutes). A recognised key is cached for five minutes, so steady traffic with a few keys never reaches this; a flood of distinct keys from one address does.	Reuse your keys instead of sending many different ones from one address.

503 Service Unavailable

If the API cannot check a key or its limits because a backing store is unavailable, keyed requests fail closed with 503 and Retry-After: 5. The body is a fixed envelope with no error field:

{
  "statusCode": 503,
  "timestamp": "2026-01-01T00:00:00.000Z",
  "path": "/v1/users/123",
  "message": "API platform temporarily unavailable; retry after 5s",
  "retryAfterSeconds": 5
}

Retry after the interval with the same request; do not retry in a tight loop.

Client guidance

• Read X-RateLimit-Remaining and slow down before you hit 0 instead of reacting to 429s.
• Honour Retry-After on both 429 and 503.
• Use one key per deployment (dev, prod) so one noisy environment does not consume another’s budget.
• Batch where a route supports it (for example POST /users/batch instead of many GET /users/{id} calls): one request is one unit regardless of batch size.