Every error an MCP gateway returns, and what to do about each one
A handful of checks run before your call reaches a publisher. The first one that fails is the error you get — and knowing the order tells you exactly where to look.
When a tool call fails through a gateway, the model reports "the tool failed" and moves on, which is the least useful sentence in software. Underneath, exactly one check refused it — and the checks run in a fixed order, so the first that fails is the error you get and none of the later ones ran.
That ordering is the whole debugging trick. If you know which check produced the code, you know which half of the system to stop looking at.
The checks, in order
- 1 · Is the key live? Revoked, expired or unknown → 401. This is the only check that runs before anybody knows which server you meant.
- 2 · Does this account hold the install? An install belongs to an account, not to a machine. A key from a device you removed is a perfectly valid key that fails here — which is why a 401 is not always a bad key.
- 3 · Is the entitlement current? An ended subscription, an expired trial, a licence for a version you are not on → 402, with what would fix it.
- 4 · Is the version still served? A withdrawn release fails closed and names the version to move to; a deprecated one keeps answering until its end date and then returns a permanent error rather than a silent one.
- 5 · Is there allowance left? Two ceilings, both hard: the plan’s calls on the install, and the account’s ceiling in money. Over either → 429, refused before the call is made.
- 6 · Is the rate inside the limit? Per-second limits, per install → 429 with a retry hint.
- 7 · Is the tool one the install approved? A release that adds a tool does not get to use it until the install accepts the new capability → 403.
Only then does the call reach the publisher. What comes back is counted on the way out — and a failure on their side should not count, because a counter that records requests rather than work is a counter that bills you for their outage.
Reading the three you will actually see
401 is a key question or an install question, and the difference is check 1 versus check 2. If whoami answers, the key is fine and the install is the problem — usually a device that was removed, or a key minted against a different account than the one holding the install.
402 is always billing, and it should always name what would fix it. It is also the check a local server cannot have, which is the whole reason a local server cannot honestly carry a subscription.
429 is three different things wearing one status code: a rate limit (wait), a monthly allowance (change the plan), or an account ceiling (raise the ceiling). The typed reason in the body is what tells them apart.
{
"jsonrpc": "2.0",
"id": 41,
"error": {
"code": -32003,
"message": "Allowance used: 6,000 calls/mo on this plan.",
"data": {
"reason": "allowance_used",
"retryable": false,
"resets": "2026-09-01T00:00:00Z"
}
}
}
This is worth insisting on when you evaluate anything that sits in front of your calls. An agent that reads retryable: false reports the refusal. An agent that gets a bare 429 tries again, and again, and files a support ticket in your voice.
The two ceilings, since one 429 is about each
Teams that set only the money one find out that a monthly maximum does not stop the maximum being spent in four minutes. Teams that set only the call one find out that eleven small subscriptions add up while every single install stayed inside its allowance.
What to do about each
| You see | It means | The fix |
|---|---|---|
| 401, whoami works | The account does not hold this install | Install it on this account, or use the key that does |
| 401, whoami fails | The key is dead | Mint a new one; check what else used it |
| 402 | Entitlement lapsed | Whatever the message names — it should be specific |
| 403 | A new tool is waiting on approval | Read what changed, then accept or do not |
| 429 reason: rate | Too fast | Back off; the hint says how long |
| 429 reason: allowance | The period’s calls are used | A larger plan, or wait for the reset |
| 429 reason: ceiling | The account’s money cap | Raise it deliberately, not reflexively |
| 410 | That release is withdrawn | Move to the version named in the error |
The debugging order that saves the most time
- whoami — is the key alive, and whose is it?
- list — does the account hold this install, and is it paused?
- What changed on the listing — did a release add a tool that is waiting on approval?
- The call log — did the call reach the publisher at all, or was it refused before it left?
Four steps, in that order, and they follow the admission path exactly. That is not a coincidence: any check that cannot be inspected afterwards is a check nobody can debug, which is a reasonable thing to demand of whatever sits in the middle of your calls.