Skip to main content

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.
How to handle: If you’re using an x402 client library (like x402-axios), this is handled automatically. The client reads the payment details, constructs a payment, and replays the request. 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.
Common causes:
  • Missing amount query parameter on /get-card
  • Amount below $5 or above $1,000
  • Missing grant_type or refresh_token in POST /auth request body
  • Invalid format parameter (must be json or html)
How to handle: Check the error message and fix the request parameters.

401 Unauthorized

Token is missing, expired, or invalid.
Common causes:
  • id_token has expired (tokens last ~1 hour)
  • Malformed Authorization header
  • Using a revoked refresh token
How to handle: Refresh your token using 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.
Common causes:
  • 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_message field explaining why)
How to handle: Ensure you’re using the correct token for the card you’re trying to access. Each wallet address has its own cards. For frozen accounts, contact support.

404 Not Found

The requested resource doesn’t exist.
Common causes:
  • Invalid card_id in /get-card-data
  • Typo in the card ID
How to handle: Verify the card_id from the original /get-card response.

429 Too Many Requests

A rate limit was exceeded.
Common causes:
  • Calling POST /refresh-card-data for 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
How to handle: Back off and retry later. For the per-card 5-minute limit, the error message includes how many seconds to wait. For the daily limit, wait until older refreshes of that card age out of the 24-hour window. Do not retry in a tight loop.

500 Internal Server Error

Something went wrong on the server.
How to handle: Retry after a few seconds. If it persists, contact support@laso.finance with the request details.

Error handling pattern

Here’s a robust error handling pattern for agent code: