HTTP status codes
The Laso Finance API uses standard HTTP status codes. Here’s what each means and how to handle it.402 Payment Required
This is the normal x402 flow — not an error. The server is telling you the price and how to pay.x402-axios), this is handled automatically. The client reads the payment details, constructs a payment, and replays the request.
A second 402: the payment failed to settle
There are two different 402s, and only the one above is routine. If your paid retry comes back 402 as well, the payment header verified but the transfer could not settle on-chain. That response carries the standard x402 settlement-failure body instead of a new challenge:accepts; a settlement failure has success: false. Branch on errorReason; errorMessage is prose and x_laso_guidance is a Laso-specific hint when one applies.
The most common cause is an underfunded wallet, and the usual reason for that is the fee. Laso fees are added on top of the amount you request, so a wallet holding exactly $2,000 cannot send a $2,000 bank payment. That request costs $2,005.00. Compare the challenge’s amount field (the fee-inclusive total, in atomic units) against your balance, then retry with a smaller amount.
Nothing is charged when settlement fails, so retrying is safe.
Note that GET /auth also returns 402 when a SIGN-IN-WITH-X header is present but fails verification (invalid or expired signature, reused nonce, domain mismatch). It does not return 401 for those failures. The 402 response carries a fresh challenge in the PAYMENT-REQUIRED response header, so sign the new challenge and retry. If you keep receiving 402 after sending a SIGN-IN-WITH-X header, treat it as a signature failure rather than retrying with the same payload.
400 Bad Request
Invalid or missing parameters.- Missing
amountquery parameter on/get-card - Amount below $5 or above $1,000
- Missing
grant_typeorrefresh_tokeninPOST /authrequest body - Invalid
formatparameter (must bejsonorhtml)
401 Unauthorized
Token is missing, expired, or invalid.id_tokenhas expired (tokens last ~1 hour)- Malformed
Authorizationheader - Using a revoked refresh token
POST /auth with grant_type: "refresh_token". If that also returns 401, re-authenticate via GET /auth.
403 Forbidden
You’re authenticated but not authorized for this resource.- Trying to access a card that belongs to a different user
- Using a token from one wallet to access another wallet’s data
- The account is frozen (the response includes a
frozen_messagefield explaining why)
404 Not Found
The requested resource doesn’t exist.- Invalid
card_idin/get-card-data - Typo in the card ID
card_id from the original /get-card response.
429 Too Many Requests
A rate limit was exceeded.- Calling
POST /refresh-card-datafor the same U.S. card less than 5 minutes after the previous refresh - Requesting more than 24 refreshes for the same U.S. card in any rolling 24-hour period