Errors

HTTP Status Codes

Code	Meaning
`200`	OK — Request succeeded
`201`	Created — Resource created
`400`	Bad Request — Invalid parameters
`401`	Unauthorized — Missing or invalid API key
`403`	Forbidden — Insufficient permissions or AML violation
`404`	Not Found — Resource doesn't exist
`409`	Conflict — Duplicate idempotency key with different parameters
`422`	Unprocessable — Valid syntax but failed business rules
`429`	Rate Limited — Too many requests
`500`	Server Error — Internal error

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "The amount field is required",
    "source": {
      "location": "body",
      "key": "amount"
    }
  }
}

Error Codes

Authentication Errors

Code	Description
`required`	Missing Api-Key header
`invalid`	Invalid API key
`expired`	API key has been revoked
`insufficient_permissions`	Key lacks required scope

Request Errors

Code	Description
`invalid_request`	Malformed request body
`missing_field`	Required field not provided
`invalid_field`	Field value is invalid
`idempotency_conflict`	Same key, different parameters

Business Logic Errors

Code	Description
`aml_violation`	Failed AML screening
`insufficient_funds`	Not enough balance
`kyc_required`	Customer KYC not approved
`unsupported_rail`	Payment rail not available
`transfer_limit_exceeded`	Amount exceeds limits

Error Handling

try {
  const transfer = await lux.transfers.create({ ... });
} catch (err) {
  if (err.code === 'aml_violation') {
    // Compliance block — do not retry
  } else if (err.code === 'insufficient_funds') {
    // Insufficient balance — notify user
  } else if (err.status === 429) {
    // Rate limited — exponential backoff
    await sleep(err.retryAfter * 1000);
  }
}

Errors

On this page