The error shape
Every/api/v2 error looks like this:
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 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 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.
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.
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.Still stuck
Write to support@agentcard.sh with four things: the endpoint you called, which credential type you used, what you expected, and what you got, with the errorcode. That’s usually enough for a same-day answer. If your coding agent is doing the integration, connect the MCP server and let it debug with you.