Errors

Every refused request, whatever the layer that refused it, answers with one JSON envelope. Branch on error; message is for humans and may change.

{
  "statusCode": 403,
  "timestamp": "2026-01-01T00:00:00.000Z",
  "path": "/v1/moderation/ban/address/abc",
  "error": "API_SCOPE_FORBIDDEN",
  "message": "Scope moderation.read required",
  "requiredScope": "moderation.read"
}

Field	Meaning
`statusCode`	The HTTP status, repeated in the body.
`error`	A stable, machine-readable code. Branch on it.
`message`	Human-readable; may change without notice.
`path`	The request path as the API saw it.
extra fields	`requiredScope` on `API_SCOPE_FORBIDDEN`; `retryAfterMs`, `limit` and `window` on `API_KEY_RATE_LIMITED`.

Platform codes

These are the codes the key, scope and limit checks can return on any route.

Code	Status	Meaning	What to do
`API_KEY_REQUIRED`	401	The keyed API host got no credential: send Authorization: Bearer <key> or x-api-key: <key>	Send the key in `Authorization: Bearer` or `x-api-key`. Do not retry the same request unchanged.
`API_KEY_INVALID`	401	The credential is not a well-formed pf_live_ key (prefix, length, charset or checksum) or no key record exists for it	Check the key: `pf_live_` prefix, 57 characters, and if you set both headers they must carry the same key. Do not retry with the same key.
`API_KEY_REVOKED`	403	The key was revoked (by its owner or by the pump.fun team); issue a new key in the developer console	Stop using this key. Create a new one in the developer console and deploy it.
`API_ORG_SUSPENDED`	403	The key's org is suspended or closed, so none of its keys is served	Stop calling. Contact support (see Status and support).
`API_ORG_NOT_APPROVED`	403	The key's org application has not been approved yet (or a key is requested before approval)	Wait for the approval decision in the developer console, then retry.
`API_SCOPE_FORBIDDEN`	403	The key does not hold the API scope this route needs; `requiredScope` names it	Request the scope named in `requiredScope` through support, or stop calling the route.
`API_KEY_RATE_LIMITED`	429	A key ceiling refused: the per-key burst bucket, the UTC daily limit (a limit of 0 means the key is paused), the per-IP failed-auth throttle, or the per-IP lookup budget; retry after `retryAfterMs`	Wait `Retry-After`, then retry. Read `window` to tell the burst bucket (`burst`), the daily limit (`day`) and the two per-IP throttles (`auth`, `lookup`) apart.
`API_CREDENTIAL_NOT_ALLOWED`	400	Each host accepts only its own credential kind	Send only an API key, and only to `api.pump.fun`. Never forward pump.fun session cookies or JWTs.
(no code)	503	The API could not verify the key or its limits (a backing store is down). Keyed requests fail closed by design. The body has no `error` field: it is the envelope with `message` and `retryAfterSeconds` (5), and the response carries `Retry-After: 5`.	Wait `Retry-After`, then retry the same request. Do not retry in a tight loop.

Route-level errors

Routes also return their own 400, 404 and 409 responses, documented per operation in the API reference. For those, error is either a registry code listed in the reference (for example USER_NOT_FOUND) or a plain HTTP reason phrase ("Not Found"). The envelope shape is the same.

One route-level code is worth knowing before you call with an API key:

400 API_USER_REQUIRED on GET /portfolio-summary and GET /portfolio-summary/chart: these routes serve the signed-in user when user is omitted, but an API key is never a session. Send user=<wallet or username> on every keyed call; do not retry unchanged.

Handling checklist

401: the key is missing or wrong. Fix the header or the key; do not retry unchanged.
403 API_KEY_REVOKED, API_ORG_SUSPENDED, API_ORG_NOT_APPROVED: stop calling and check the developer console.
403 API_SCOPE_FORBIDDEN: request the scope in requiredScope.
429: wait Retry-After, then retry. Check window to know whether it was the burst bucket (burst), the daily limit (day) or one of the per-IP throttles (auth, lookup); see Limits and headers.
503 with no error field: wait Retry-After (5 seconds), then retry the same request.
Anything else: read error, log X-Request-Id, and quote both in a support request.