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. 
{
  "x402Version": 1,
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "maxAmountRequired": "5000000",
      "resource": "https://laso.finance/get-card?amount=5",
      "description": "Get Laso Finance prepaid card",
      "payTo": "0x3291e96b3bff7ed56e3ca8364273c5b4654b2b37"
    }
  ]
}
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. 
{
  "error": "Amount must be at least $5. Received: $2"
}
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. 
{
  "error": "Invalid or expired token"
}
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. 
{
  "error": "Not authorized to view this card"
}
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. 
{
  "error": "Card not found"
}
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. 
{
  "error": "Daily card refresh limit reached. You can request at most 24 refreshes for a card in a 24-hour period. Please try again later."
}
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. 
{
  "error": "Failed to order card. Please contact support."
}
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: 
async function safeApiCall(fn) {
  try {
    return await fn();
  } catch (error) {
    const status = error.response?.status;
    const message = error.response?.data?.error;

    switch (status) {
      case 400:
        console.error("Bad request:", message);
        throw new Error(`Invalid request: ${message}`);
      case 401:
        console.log("Token expired, refreshing...");
        await refreshTokens();
        return await fn(); // Retry with new token
      case 403:
        console.error("Not authorized:", message);
        throw new Error(`Access denied: ${message}`);
      case 404:
        console.error("Not found:", message);
        throw new Error(`Resource not found: ${message}`);
      default:
        console.error(`Unexpected error (${status}):`, message);
        throw error;
    }
  }
}