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.

​
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 or /send-payment
  • 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)
  • Missing platform or recipient_id on /send-payment
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
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.

​
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.

​
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;
    }
  }
}