> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and troubleshooting

> The error shape, what each error means, and what to send us if you're stuck.

## The error shape

Every `/api/v2` error looks like this:

```json theme={null}
{
  "error": {
    "code": "user_info_required",
    "message": "Recorded consent is required before creating a wallet link.",
    "docs": "https://docs.agentcard.sh"
  }
}
```

`code` is stable and worth branching on; `message` is for humans and can change. Some older surfaces still return a flat `{ "error": "...", "message": "..." }` shape. If you're on `/api/v2`, you'll always get the nested one.

## Check these first

If something isn't working, run down this list in order.

**1. The credential and the call.** An org token where a connection token belongs, or a wallet link treated like a session. The [keys and tokens table](/wallet/connect-users#keys-and-tokens) settles it; every credential has exactly one place it goes.

**2. Hand-building flows the wallet already runs.** If you're implementing card entry, identity verification, or balance screens against the API, stop. The wallet does all of it, and the API-only versions exist for a different kind of product. Read [How the wallet works](/wallet/how-the-wallet-works) before writing more code.

**3. `user_info_required` when creating wallet links.** Consent was never recorded for that user. Call `POST /api/v2/connect/consent` once after the user verifies, then create links freely.

**4. `subscription_required` (402) in production.** Production credentials act only while a subscription is active. Sandbox never needs one. See [Go live](/ship/go-live).

**5. Testing blind in sandbox.** Sandbox never tells you its shortcuts exist. The code is `111111`, the test card is `4242 4242 4242 4242`, and everything else is on [Test in sandbox](/ship/test-in-sandbox).

**6. A funding model that won't change.** User-funded versus company balance locks at your first live transaction. If you need to change it after that, talk to us.

## Webhook signatures failing

Almost always one of two things: you verified against a re-serialized body instead of the raw bytes, or you used another endpoint's secret. The verification recipe is on [Webhooks](/wallet/webhooks#verify-the-signature).

## Still stuck

Write to [support@agentcard.sh](mailto:support@agentcard.sh) with four things: the endpoint you called, which credential type you used, what you expected, and what you got, with the error `code`. That's usually enough for a same-day answer. If your coding agent is doing the integration, connect the [MCP server](/tools/mcp) and let it debug with you.