Snapback tells an AI agent why it failed and how to fix it — fast enough to self-correct. These guides cover what that means, what it costs, what it covers, and how to wire it in.
A practical guide: your agent hits an HTTP 402, needs to pay in USDC, and either has a wallet or doesn't. Here's the full flow for EVM and Solana — plus the free no-wallet path so a bare agent isn't stuck.
A Snapback is one completed diagnosis of why an AI agent failed, plus the fix. How self-healing agents diagnose loops, hallucinated tool schemas, API timeouts and burned budgets — and self-correct mid-run.
What's free in Snapback, what a diagnosis costs, and how pay-as-you-go x402 payments work on Solana and EVM chains — about $0.0032 USDC per Snapback, no account required.
Snapback diagnoses agent failures across 46 infrastructure families — payments, on-chain, protocol, infra, messaging, data, enterprise, travel, and auth — plus behavioural failures like loops and hallucinated tool schemas.
Connect Snapback to any MCP-capable agent — OpenClaw, GitHub Copilot, Hermes, Claude, Cursor — in minutes. Register the MCP server, call the free tools, diagnose a failed run, and pay per call with x402.
Autonomous AI agents rarely crash with a stack trace. They loop, stall, hallucinate tool schemas, and burn budgets quietly. Here's why observability shows you that a run failed but not why — and what closes the gap.
How autonomous on-chain agents pay for a Snapback diagnosis with x402 — an HTTP 402, a USDC payment signed from the agent's own wallet, on Solana or EVM. No account, no card, no human in the loop.
The cheapest agent failure to fix is the one you catch before it happens. How detect_loop and budget_guard watch a run in real time and flag a repeating tool call or a runaway token/cost burn before the step limit — free, no token, no LLM.
How Snapback handles sensitive trace data — server-side redaction, org-scoped tokens, and no secrets returned — plus the self-hosted deployment coming for teams with data-residency or air-gap requirements.
Your AI agent keeps calling the same tool with the same inputs until it hits the step limit and burns your token budget. Here's why it happens, how to detect a repeated-tool-call loop in real time, and how to stop it — with a free check that needs no token.
Woke up to a surprise API bill because an agent ran all night doing nothing useful? Here's how to catch runaway token and cost burn mid-run — context overflow, token-burn rate, and step budgets — with a free guard that returns in under 150ms and no LLM.
Your agent run ends with "stopped due to iteration limit or time limit" and no result. That cap firing is a symptom, not the cause. Here's what's actually happening, how to find the real reason, and how to stop hitting the limit.
An agent tool call returns a terse, cryptic error — "unable to get local issuer certificate," a 410, a Kafka CommitFailedException, an Amadeus 34651 — and the model misdiagnoses it. Here's how to map any cryptic infrastructure error to its real cause and fix, free, across 46 families.
Your agent calls a function with arguments you never defined — an invalid parameter, a missing required field, a made-up flag — and it fails validation before the tool even runs (AI_InvalidToolArgumentsError). Here's why models hallucinate tool arguments and how to catch it.
Your agent has the right tools available but reaches for the wrong one — using search when it should calculate, or a generic tool over the specific one — and the task quietly goes sideways. Here's why models mis-select tools and how to catch it.
As a run gets long, the context window fills — and tool definitions, earlier results, or the original goal get pushed out of scope. The agent starts hallucinating, forgetting instructions, or mis-calling tools. Here's how to spot and fix context overflow before it degrades the run.
In a multi-agent setup, one agent's bad output becomes another's input — and a single early mistake propagates into several confident, coherent, wrong answers with no exception raised. Here's why orchestration amplifies failures and how to trace them to the source.
Your agent's output was supposed to be JSON (or match a schema) and it wasn't — an extra sentence, a trailing comma, a truncated object — so the downstream step that parsed it broke. Here's why agents produce malformed output and how to make it reliable.
Your Amadeus Flight Create Orders call fails with code 34651, 'SEGMENT SELL FAILURE', 'Could not sell segment' — the seat isn't available at booking time. Retrying the same offer won't help. Here's why it happens and how to fix the search-to-book flow.
Your Amadeus flight booking fails with 400 MANDATORY DATA MISSING — missing travelerPricings, source, or segment IDs. The cause is almost always passing a simplified flight offer instead of the complete raw one, or skipping the mandatory Flight Offers Price step. Here's the fix.
A Stripe payment came back with outcome.type 'blocked', reason 'highest_risk_level', advice_code 'do_not_try_again' — Radar blocked it before it reached the network. Retrying is futile. Here's what the outcome fields mean and what to do instead.
An ACH debit came back blocked (bank_account_unusable, HTTP 402) or with a NACHA return like R10 unauthorized — and NACHA rules require you resolve the root cause before re-debiting. Retrying is a rules violation. Here's how to handle blocked bank accounts and unauthorized returns.
Your Solana transaction reverted or vanished — a missing Associated Token Account, a BlockhashNotFound / expired blockhash, or a transaction silently dropped for exceeding its compute budget. These aren't the same failure. Here's how to tell them apart and fix each.
Your agent hits an x402 endpoint, gets an HTTP 402 Payment Required, and then stalls — it can't parse the requirements, signs the wrong scheme, or retries without attaching payment. Here's how the x402 flow works and where agents get stuck, on Solana and EVM.
Your app hit 'deadlock detected' (40P01) or 'could not serialize access' (40001) under load. These are transient and retryable — but only if you retry the whole transaction, idempotently, with backoff. Here's the correct retry policy and how to prevent them.
Your token refresh fails with 'invalid_grant' and retrying just fails again. invalid_grant means the grant is dead — you can't refresh out of it; the user must re-authenticate. Here's what causes it (single-use code reuse, revoked/expired refresh tokens, concurrent refresh races) and how to handle it.
You're wiring an MCP server and your tool calls fail with -32601 (method not found), -32602 (invalid params), or -32700 (parse error / stdout corruption). Here's what each JSON-RPC code means for MCP, the common causes, and the fix — including the top mistake: calling a tool as a top-level method.
Your blockchain RPC calls fail with HTTP 429 / JSON-RPC -32005 'limit exceeded', -32601 'method not found', or you're reading stale data because the node is behind the chain tip. Here's what each means and how to handle RPC reliability.
Your SQS DeleteMessage fails with ReceiptHandleIsInvalid, or Kafka throws CommitFailedException — and the real danger is silent duplicate processing. Here's why the visibility timeout and poll interval matter, and how to stop reprocessing the same message.
Your container keeps dying with exit code 137 / OOMKilled, or a pod is stuck in CrashLoopBackOff restarting forever. These look similar but aren't the same. Here's how to tell an out-of-memory kill from a crash loop and fix each.
Your agent or app hits EACCES 'permission denied', EROFS 'read-only file system', ENOSPC, or EBUSY inside a container — and the cause is usually the container environment, not your code. Here's what each really means in a sandbox and how to fix it.
Your Google/Microsoft calendar sync fails with 412 Precondition Failed (ETag) or 410 Gone (sync token). A blind retry double-books; treating 410 as auth wastes time. Here's what each means and the correct handling.
Your CCTP cross-chain USDC transfer won't mint on the destination — the attestation is still pending_confirmations, or Circle's Iris API returns 404. These aren't failures; you're polling before the attestation is ready. Here's the correct flow.
Your Solana token operation fails with 'incorrect program id for instruction', or a transfer silently under-delivers because of a transfer fee. The mint is a Token-2022 mint and you're treating it like a classic SPL Token. Here's how to handle Token-2022 extensions.
Your Solana dApp fails with Phantom error 4900 'disconnected', 4100 'unauthorized', or a -32603 deeplink error. Each means something specific about the wallet connection state. Here's how to connect and transact reliably.
You upsert a vector, immediately query, and it's not there — or you get the old value. Vector databases are eventually consistent; an upsert isn't instantly visible to reads. Here's why sleeping is the wrong fix and what to do instead.
A webhook that worked for months suddenly breaks — a field moved or vanished (payload schema drift) — or the error body is an RFC 9457 application/problem+json document you're not parsing. Here's how to make webhook handling resilient.
Your AirnodeHub / API3 integration fails attestation verification (the signature doesn't recover to the expected signer), or a resolve call returns nothing. Here's what attested-data failures mean and how to handle them.
If your AI agent talks to users through a chat interface — Telegram, Slack, Discord — a slow diagnosis round-trip and a giant JSON response break the experience. Here's how to call Snapback reliably from a chat agent: format:"summary_only" for a one-line relayable answer, which tools are instant, and why live sessions don't fit chat.
Your agent hits the same fixable errors over and over — a missing ATA, an expired cert, a deadlock — and you fix them by hand. Here's how to make it self-heal: auto-diagnose every error, apply the fix if it's safe, retry once, escalate if not. No human in the loop.
Letting an agent act on a diagnosis without a human check is powerful and dangerous. Here's the machine-readable gate that decides when it's safe — confidence, source, and reversibility — and why 'source: library vs LLM' is the field that unlocks trust.
When your agent hits a failure, the most useful question isn't just 'what's the fix' — it's 'what did other agents try, and what actually worked?' Here's how a shared, anonymized library of agent outcomes becomes a debugging engine that gets sharper the more agents use it.
A Snapback verdict returns confidence, source, action_class, and a gate. Here's what each field means, when to trust a verdict versus escalate to a human, and why a confidence of 0.55 is a red flag you should never auto-act on.
Your pod is stuck in ImagePullBackOff, an admission webhook denied it, or it won't schedule — and re-applying the deployment does nothing. The status label isn't the diagnosis; the Pod events are. Here's what each state means and the fix.
Your service mesh returns 503 and retrying doesn't help. In Istio/Envoy the HTTP 503 is meaningless on its own — the Envoy response flag (UF, UO, NR) tells you whether it's a connection failure, a tripped circuit breaker, or a missing route. Here's how to read them.
GitHub and Shopify GraphQL APIs return HTTP 200 with a THROTTLED or RATE_LIMITED error in the body — so status-code-only retry logic records it as success and silently drops your data. Here's how to detect it and compute the right wait.
A Stripe payment declined with authentication_required or a PaymentIntent stuck at requires_action means the bank wants 3D Secure / SCA — the card is valid. Retrying the same charge off-session fails identically. Here's the correct flow.
A Lambda 429 / Rate Exceeded has two different causes with opposite fixes — a rate throttle vs a concurrency-ceiling throttle. And async throttling is silent: the invoke returns 202, then the event is retried twice and dropped to the DLQ. Here's how to tell them apart.
A Twilio queued/201 is not delivery — the carrier can silently filter it. Codes 30007 (filtered) and 30034 (unregistered 10DLC) are compliance failures that fail identically on retry. And 30003 vs 30006 look alike but have opposite fixes. Here's the map.
A clean 999 (syntax accepted) with a rejected 277CA means the file was valid but the claim failed payer edits — and 277CA acceptance is before adjudication, so it doesn't mean payment. On the 835, the CAS group code (CO vs PR) decides who pays, and getting it wrong is a compliance violation.
A Terraform ConditionalCheckFailedException state-lock error is usually a stale lock from a crashed CI job — but force-unlocking while a real apply is running corrupts your state. Read the Lock Info first. Here's the safe fix.
A Delta Lake ConcurrentAppendException fires even when two jobs write to different partitions — because WriteSerializable isolation detects conflicts more coarsely than you'd expect. Blind-retrying loops. Here's the real fix.
A Persona/Socure/Alloy identity check returning REVIEW or pending_manual_review isn't a failure to retry — it's a routing decision. And re-submitting a REJECT trips fraud velocity rules. Here's how to handle KYC decisions correctly.
The 403 'Resource not accessible by integration' in GitHub Actions is almost always the GITHUB_TOKEN being read-only by default since 2023. Add a least-privilege permissions block — not write-all. Here's the fix.
The Redis 'OOM command not allowed when used memory > maxmemory' error isn't a container OOMKill and restarting won't fix it. It's the noeviction policy rejecting writes while still serving reads. Here's the real fix.
The Elasticsearch circuit_breaking_exception returns HTTP 429 so it looks like throttling — but it's a memory guard preventing an OOM. Retrying or raising the limit makes it worse. Here's the real fix.
A Microsoft Graph 403 Authorization_RequestDenied is a permissions/consent problem that retrying never fixes — while a 429 carries a mandatory Retry-After. Telling them apart is the whole game. Here's how.
In real-time bidding, a 204 No Content is the normal no-bid signal, not a failure. Retrying it spams the auction. And the nbr / AUCTION_LOSS codes are how you diagnose a low win-rate. Here's the protocol.