Errors and recovery

Result	Action
REST 400	Correct the required query text, bounds or zone.
REST / MCP auth 401	Check audience, scope and expiry. Renew once where appropriate.
REST 404	Refresh the set or card ID from catalogue results.
Authenticated MCP GET 405	Expected: connect with an MCP client using POST.
MCP isError: true	Inspect the safe tool message; the lookup did not succeed.
Network / server error	Retry reads with bounded backoff and jitter.

Missing scope returns 401, not a distinct 403. Do not match error prose to decide application behavior. Invalid MCP arguments may be rejected by the SDK before a tool handler runs.

An MCP protocol response is not proof of a successful card lookup: inspect isError. Repeated token exchanges do not repair a catalogue outage.

For help, include the endpoint/tool, UTC timestamp, status, and a sanitized reproduction. Never send authorization headers or secrets.