Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nicosaporiti/buda-lightning-invoice/llms.txt

Use this file to discover all available pages before exploring further.

The Buda Lightning Invoice API returns two distinct error shapes. Validation errors are produced by the express-validator middleware when a request field is missing or does not meet its rules — they arrive before any business logic runs. Application errors are produced when the controller or an internal Buda.com API call fails — they carry a plain error string instead of a field map. Both shapes use HTTP 400 Bad Request and always include "ok": false.

​
Validation Errors (400)

Validation errors are returned when one or more request fields fail their express-validator checks. The response contains an errors object whose keys are the failing field names, produced by express-validator’s errors.mapped() method. Each field entry includes at minimum a msg property with the human-readable error message. 
{
  "ok": false,
  "errors": {
    "fieldName": {
      "msg": "Human-readable error message"
    }
  }
}
Multiple fields can fail at once. Every failing field gets its own key inside errors, each with a msg property.
amount on POST /newinvoice — triggered when amount is missing, non-numeric, or less than 1 satoshi: 
{
  "ok": false,
  "errors": {
    "amount": {
      "msg": "Ingrese un número entero mayor a 1"
    }
  }
}
msg on POST /newinvoice — triggered when msg is absent or an empty string: 
{
  "ok": false,
  "errors": {
    "msg": {
      "msg": "Debe ingresar un mensaje"
    }
  }
}
invoice on POST /status — triggered when invoice is missing or not a string: 
{
  "ok": false,
  "errors": {
    "invoice": {
      "msg": "Ingrese invoice"
    }
  }
}
amount on GET /callback — triggered when amount is missing, non-numeric, or less than 1000 millisatoshis: 
{
  "ok": false,
  "errors": {
    "amount": {
      "msg": "Ingrese un número entero mayor a 1000 msats"
    }
  }
}

​
Application Errors (400)

Application errors are returned when business logic fails or a Buda.com API call does not succeed. The response contains a single error string instead of a field map. 
{
  "ok": false,
  "error": "Buda error 422: {\"message\": \"..\"}"
}
Error patternWhen it occurs
"Buda error {statusCode}: {body}"The Buda.com API responded with a non-success HTTP status. statusCode is the upstream HTTP code; body is the raw response body.
"Buda error: {message}"A network or runtime error occurred while communicating with Buda.com (e.g. timeout, DNS failure, connection refused).
A 400 response from this API does not always mean the client sent a bad request. It may also indicate a transient upstream failure from Buda.com. Inspect the error string to distinguish the two cases.

​
Validation Rules Summary

FieldEndpointRuleError message
amountPOST /newinvoiceRequired integer, minimum value 1 (satoshis)Ingrese un número entero mayor a 1
msgPOST /newinvoiceRequired non-empty string, minimum length 1Debe ingresar un mensaje
invoicePOST /statusRequired non-empty stringIngrese invoice
amountGET /callbackRequired integer, minimum value 1000 (millisatoshis)Ingrese un número entero mayor a 1000 msats
/newinvoice and /status accept a JSON body (Content-Type: application/json). The /callback endpoint reads amount and comment from the URL query string — no request body is used.

​
Handling Errors in Code

The example below shows how to detect and handle both error shapes in a single fetch call. 
const res = await fetch('https://budaln.fly.dev/newinvoice', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 1000, msg: 'Coffee' })
});
const data = await res.json();

if (!res.ok) {
  if (data.errors) {
    // Validation error — one or more fields failed their rules
    const messages = Object.values(data.errors).map(e => e.msg);
    console.error('Validation:', messages.join(', '));
  } else {
    // Application error — Buda.com API failure or business logic error
    console.error('Error:', data.error);
  }
}
The key distinction is the presence of the errors key (an object of field errors from express-validator) versus the error key (a plain string from the controller catch block). Checking data.errors first handles the validation case; the else branch covers all application-level failures.

Build docs developers (and LLMs) love

Get started for freeTalk to us