Errors

What each failure means, and whether retrying is the right answer. A refusal from this gateway names what was wrong rather than returning an empty result, so a failed call is safe to read literally.

HTTP status codes

What you see	What it means	What to do
401	Missing, malformed, revoked, expired or unknown credential.	Check the header spelling first, then issue a fresh key from the dashboard. If a connector worked yesterday and not today, its authorization may have been revoked from Connectors.
400 · Missing session ID	A request arrived without the MCP session handshake.	Call `initialize`, keep the `Mcp-Session-Id` response header, send `notifications/initialized`, then retry. See the by-hand quickstart.
404 · unknown path	The source slug does not exist, or a per-source endpoint was misspelled.	Check the slug against the catalogue. Slugs are hyphenated, and the tool prefix on the aggregate endpoint uses underscores instead.
429	Too many requests in too short a window, against the per-minute ceiling.	Back off and retry. This ceiling exists to stop a runaway loop, not to ration your plan, so a well behaved client rarely meets it.
5xx	The gateway or an upstream source failed.	Retry with backoff. Repeated failures are reported on status.

Tool errors and refusals

A tool error is a successful HTTP response carrying a failure. That distinction matters: a 200 with an error body means your credential and session were fine and the call itself was declined.

What you see	What it means	Retrying
quota	The rolling 24 hour or hourly cap for the plan is reached.	Not until the window rolls. Spread calls across keys, or ask for more capacity.
upstream	The government source refused, timed out or rate limited the call.	Yes, with backoff. The ceiling is external and set by someone else.
invalid arguments	A required argument was missing or outside its accepted range.	No. The message names the argument. Read the tool's schema from `tools/list`.
not covered	A cached dataset does not hold the window or code you asked for.	No, and the message says which coverage exists. This is deliberately a refusal rather than an empty result, because an empty result would read as "nothing exists".
needs a credential	The source draws on your own upstream key and none is attached.	No. Attach one from Upstream keys.

When you hit a limit

Two ceilings matter, and they are different things.

Your plan's quota is yours: a rolling 24 hour allowance, with an hourly ceiling and a short burst ceiling above it. The burst and hourly ceilings exist to stop a runaway loop from burning a day's allowance in a minute. Exceeding any of them returns a tool error naming the limit, and nothing is charged as overage.
A shared upstream ceiling is not yours and is not a plan feature. Some agencies cap how much anyone may draw per day. A bigger plan buys no additional upstream capacity, which is why the refusal for that case is worded differently and retrying before the stated time will not succeed.

Every refusal names the window it hit and when that window rolls off, as an absolute timestamp. Usage shows all three windows against their limits, and Billing is the page a refusal links to for the full explanation and the route to more capacity.