Rate Limits, Credits & Errors

Rate-limit headers, credit spend, and the JSON-RPC error codes the PowerNames MCP server returns — and how to handle each.

Two independent budgets govern every call: a rate limit on how often you call, and credits for the analysis work you run.

Rate limits

Each API key has a rate-limit tier. Every response carries the current window's state, so your client can pace itself:

Header	Meaning
`X-RateLimit-Limit`	Calls allowed in the current window
`X-RateLimit-Remaining`	Calls left in the window
`X-RateLimit-Reset`	Unix time (seconds) when the window resets

When you exceed the limit the server responds with:

HTTP 429
JSON-RPC error code -32029 ("Rate limit exceeded")
a Retry-After header (seconds to wait)

Back off for Retry-After seconds and retry. Read X-RateLimit-Remaining proactively to avoid hitting the wall.

Credits

Credits are consumed by tools that run an analysis or reach an external service — the ⚡ tools in the tool reference:

run_full_analysis, score_name, analyze_linguistics
check_global_risk, check_trademark
check_name_availability (only when project-scoped), check_single_domain, check_single_social

Reads (list_*, get_*, compare_names) and plain mutations (create_project, add_names, shortlist_name, rate_name) don't spend credits.

Every call runs under a per-call credit budget — the same ceiling one agent turn gets in the product. A single call that would chain past that budget is stopped rather than draining your balance unexpectedly. Credits are shared by the whole team the key belongs to; top them up from the app when the balance runs low.

Error codes

Errors come back as standard JSON-RPC error objects: { "jsonrpc": "2.0", "error": { "code", "message" }, "id" }.

HTTP	Code	Meaning	What to do
`401`	`-32001`	Missing/invalid `Authorization` header, or invalid/expired key	Check the `Bearer pn_live_…` header; reissue the key if needed
`429`	`-32029`	Rate limit exceeded	Wait `Retry-After` seconds, then retry
`500`	`-32603`	Internal error while handling the request	Retry with backoff; if it persists, capture the message and contact support

Tool-level problems (a bad name_id, an out-of-range value, a missing project) come back as a normal tool result describing the issue, not as a transport error — so read the tool's JSON payload, not just the HTTP status.

Handling checklist

Send Authorization: Bearer pn_live_… on every request.
Watch X-RateLimit-Remaining; honour Retry-After on 429.
Expect analysis tools to be asynchronous — poll get_analysis_status rather than blocking.
Keep credit-spending calls deliberate; batch reads freely.
Keep the returned auditId so you can undo a mutation if needed.