Errors
The status codes the Walletguide API returns, what each one means, and what to do about it.
Errors come back as JSON with an error field, at the status code the situation warrants.
{ "error": "Wallet not found" }| Status | What happened | What to do |
|---|---|---|
400 | The request did not validate | Read the message; it names the field |
401 | No credential, or it was rejected | See below |
403 | Authenticated, but not allowed | Wrong wallet, a permission the member or key does not hold (named in missing), or a scope the grant does not have. Code WALLET_INACTIVE: see below |
404 | No such thing here | Also what you get for an id in another wallet |
409 | It conflicts with what is already there | Usually a duplicate |
429 | Too many requests | Back off and retry |
5xx | Ours | Retry with backoff; tell us if it persists |
Reading a 401
Three different things share this code, and they need different fixes.
The token is opaque rather than a JWT. The token request did not carry an RFC 8707 resource parameter, so the provider issued an opaque token, and the api verifies against the JWKS. Send resource on the token request as well as the authorization request.
The audience is wrong. The token was minted for …/mcp and presented to a REST route, or the other way round. Sign in again against the right audience.
It really was rejected. Expired, or the grant was revoked. Refresh, and if that fails, sign in again.
The CLI works out which of the three it is and says so. If you are building your own client, decoding the token's aud claim and comparing it to https://api.walletguide.com answers it in one line.
An inactive wallet
When the wallet owner's trial has run out or their subscription has ended, the wallet becomes inactive. Every /wallets/{walletId} route then answers 403 with a code:
{ "error": "This wallet is inactive because its owner has no active Walletguide plan. …", "code": "WALLET_INACTIVE" }The data is still there. Access comes back as soon as the owner subscribes in the web app. GET /wallets still lists the wallet, with active: false, and the owner can still delete it. An API key of an inactive wallet is refused earlier, with a 401.
A 404 that is really a 403
An id belonging to another wallet answers 404, not 403. That is deliberate: a 403 would confirm the row exists, which is a thing you are not entitled to know.