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, wrong role, or a scope the grant does not have |
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.
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.