Troubleshooting
Common errors an agent, MCP client, or proxy call can hit, what causes them, and how to fix them.
Start here when a credential fetch, MCP call, or proxy request fails. Match the code or symptom, then jump to the section below for detail.
| Symptom / code | Cause | Fix |
|---|---|---|
404 NO_GRANT | Agent has no grant for that service (or it expired) | Grant the service to the agent, or check the service name for typos |
403 POLICY_DENIED | An ABAC policy attached to the agent/proxy/token denied the request | Read the policy field in the response and adjust or remove that policy |
429 with Retry-After (REST) or JSON-RPC -32029 (MCP) | Rate limited, or the penalty box is engaged | Wait Retry-After seconds, then retry |
423 VAULT_LOCKED | The kill switch ("Stop all access") is engaged | Resume access |
401 REAUTH_REQUIRED | The action needs a sign-in within the last 5 minutes | Sign in again, then retry |
502 WEBHOOK_UNAVAILABLE / WEBHOOK_AUTH_FAILED / WEBHOOK_REDIRECT_BLOCKED | Your webhook is unreachable, rejected the request, or answered with a redirect | See Webhook unreachable below |
| MCP client keeps asking to sign in | Its session expired or was revoked (e.g. by a webhook rebind) | Reconnect — the client re-authorizes automatically |
403 AGENT_INACTIVE / 401 invalid_grant "Agent is suspended" | The agent (or its MCP session) is suspended | Reactivate the agent, or leave it suspended if that's intentional |
NO_GRANT
404 NO_GRANT means the agent authenticated fine but has no live grant for the service it asked for — either it was never granted, or the grant expired. This is deliberately ambiguous: Token Vault doesn't distinguish "never granted" from "expired" in the response, so a probing caller can't learn which services exist on your account. It's also never a strike against the agent — no penalty-box lockout — because typos and stale configs are common and not malicious. Repeated misses are rate-limited on their own scope, capped at 10 per minute per agent, so a broken agent can't hammer Firestore even though it isn't punished for it.
POLICY_DENIED
An ABAC policy attached to the agent, proxy, or token denied the request. On REST endpoints this is HTTP 403; on an MCP tool call it comes back as a tool result with isError: true rather than a transport-level error. Either way, the response's policy field names the specific policy that denied it — check that policy's rules (time window, IP allowlist, rate limit, usage cap, geo restriction, or manual approval) against what the agent just tried to do.
Manual approval policies currently deny
Token Vault has no push notification channel right now, so a manual_approval policy fails closed instead of prompting anyone — every request it covers is denied. Remove or replace that policy type until a replacement channel ships.
Rate limited
A 429 (REST) or JSON-RPC error -32029 (MCP) means you've exceeded a rate limit. Every response carries a retryAfter value and, on REST, a matching Retry-After header — wait that long before retrying. See Rate limits for the full table of limits.
Repeated rate-limit violations for certain scopes (not NO_GRANT misses) escalate into the penalty box: an exponential backoff lockout starting at 1 second and doubling per strike, capped at 15 minutes. A strike decays after an hour of good behavior.
VAULT_LOCKED
423 VAULT_LOCKED means the account's kill switch is engaged — see Stop all access. Every agent, proxy, and MCP path is refused until the owner resumes access.
REAUTH_REQUIRED
401 REAUTH_REQUIRED means the action needs a sign-in within the last 5 minutes, and your current session is older than that. This guards the highest-impact actions: resuming access after a lock, rebinding or deleting the vault, changing the webhook URL, creating a proxy or changing its upstream, creating an agent, and adding a redirect host. Sign in again and retry — it isn't required for merely viewing data or revealing an existing key.
Webhook unreachable / auth_failed / redirect refused
These three codes all mean Token Vault tried to reach your webhook and something went wrong on that leg:
WEBHOOK_UNAVAILABLE(502) — Token Vault couldn't reach your webhook at all (DNS failure, connection refused, timeout). Check that your webhook is deployed and its URL is correct in Settings → Webhook.WEBHOOK_AUTH_FAILED(502) — your webhook rejected Token Vault's HMAC-signed request. This usually means the HMAC secret the two sides share is out of sync — most often after a webhook redeploy that lost its persisted secret. Re-bind the webhook.WEBHOOK_REDIRECT_BLOCKED(502) — your webhook responded with an HTTP redirect. Token Vault never follows a webhook-originated redirect (it would replay a signed request to a host you never bound), so this is always treated as a hard failure. Check your webhook isn't sitting behind something that redirects (a load balancer forcing HTTPS, a auth wall, etc).
Also watch for WEBHOOK_NOT_CONFIGURED (502) — no webhook is bound yet; finish setup first — and WEBHOOK_CIRCUIT_OPEN (503) — your webhook has failed repeatedly and Token Vault has paused calling it for a bit; wait for the Retry-After and it'll try again automatically. Settings → Webhook shows the last health check result and status.
An MCP OAuth client needs to sign in again
MCP OAuth sessions (tvsess_/tvrefresh_) are revoked whenever something invalidates the standing trust behind them — most commonly changing your webhook URL, which revokes every OAuth session across the account, or suspending the specific agent identity a session is bound to. When that happens, the client's next call gets 401 invalid_token (or the refresh attempt gets 400 invalid_grant), and the client should fall back to its normal OAuth flow — reconnect and re-authorize. This is expected, not a bug.
Agent suspended
A suspended agent's REST credential calls get 403 AGENT_INACTIVE ("Agent is suspended or deleted"), its MCP tool calls get an equivalent 401 (inviting re-auth, since suspension can be reversed), and its MCP OAuth token refresh gets 400 invalid_grant ("Agent is suspended"). Reactivate the agent from the dashboard if the suspension wasn't intentional; suspending is one of the reduce-only actions that still works even while the vault is locked.