Error Codes

This page describes common API error codes and recommended recovery actions. Always inspect both the HTTP status and the payment or operation result.

Error Response Format

Current gateway errors include a string message, error_code and timestamp. Ticket business failures can instead contain success: false, error and statusCode; see the Tickets guide. For example:

{
  "statusCode": 400,
  "message": "Human-readable error message",
  "error_code": "ERROR_CODE",
  "timestamp": "2025-01-28T10:00:00.000Z"
}

HTTP Status Codes

Status Code	Meaning
`200`	Success
`201`	Created
`204`	No Content (successful deletion)
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error
`503`	Service Unavailable

Payment Error Codes Quick Reference

The following codes can appear in a failed payment result or an HTTP error. A business failure may be returned inside an otherwise successful HTTP response; do not infer payment completion from HTTP status alone.

Error Code	HTTP Status	Description	Recoverable
`INSUFFICIENT_BALANCE`	400	Merchant balance too low for withdrawal	✅ Wait for deposits
`MISSING_REQUISITES`	400	No payment route is currently available for this request	✅ Wait/retry
`NO_AVAILABLE_REQUISITES`	400	Payment routes are temporarily unavailable	✅ Wait/retry
`INVALID_METHOD`	400	Payment method not configured or inactive	❌ Contact support
`INVALID_WITHDRAWAL_DATA`	400	Invalid payout details (bank account, etc.)	✅ Fix data
`UNSUPPORTED_CURRENCY`	400	Currency not supported	❌ Use different currency
`WITHDRAWAL_NOT_SUPPORTED`	400	Method doesn’t support withdrawals	❌ Use different method
`MERCHANT_REFERENCE_DUPLICATE`	200	Payment with this reference exists	⚠️ Returns existing
`VALIDATION_ERROR`	400	Request validation failed	✅ Fix request
`PROVIDER_ERROR`	500	Payment provider returned an error	✅ Retry later
`PAYMENT_CREATE_OUTCOME_UNKNOWN`	502	An HTTP creation response could not be verified after the request may have been accepted	⚠️ Verify the original order before retrying
`FASTOO_PAYOUT_NOT_READY`	Payment response	Fastoo payouts are unavailable for the requested route and currency	Confirm route availability with support and check the original payment before retrying
`TEAM_BALANCE_FREEZE_TIMEOUT`	Payment response	Payment creation could not complete within its deadline; check the original payment before retrying	⚠️ Inspect the existing payment; do not blindly replay a financial operation
`TTL_EXPIRED`	400	Payment expired before completion	❌ Create new payment
`LOCK_TIMEOUT`	400	Payment processing was temporarily busy	✅ Retry
`TRANSACTION_ERROR`	500	Transaction processing error	✅ Retry
`INVALID_CLABE`	400	Invalid CLABE format (18 digits)	✅ Fix data
`INVALID_CVU`	400	Invalid CVU format (22 digits)	✅ Fix data
`INVALID_BSB`	400	Invalid BSB format (6 digits, `XXX-XXX`)	✅ Fix data
`INVALID_PAYID`	400	Invalid PayID identifier	✅ Fix data
`PAYID_NOT_FOUND`	400	PayID identifier not registered in NPP	✅ Verify with recipient
`LIMIT_EXCEEDED`	400	Transaction limit exceeded	❌ Reduce amount
`DAILY_LIMIT_EXCEEDED`	400	Daily transaction limit reached	❌ Wait for next day
`MONTHLY_LIMIT_EXCEEDED`	400	Monthly transaction limit reached	❌ Wait for next month
`METHOD_NOT_AVAILABLE`	400	Payment method not available	❌ Use different method
`METHOD_NOT_CONFIGURED`	400	Payment method not configured for merchant	❌ Contact support
`DUPLICATE_REFERENCE`	400	Duplicate reference detected	⚠️ Use unique reference
`PAYMENT_ALREADY_PROCESSED`	400	Payment already in terminal status	❌ Cannot modify
`PAYMENT_ALREADY_EXISTS`	400	Payment already exists	⚠️ Returns existing
`DATABASE_ERROR`	500	Payment processing failed	✅ Retry
`TIMEOUT`	504	Operation timed out	✅ Retry

Recoverable errors (✅) can often be resolved by correcting data or contacting support. They do not guarantee that repeating a financial request is safe. Non-recoverable errors (❌) require configuration changes or using different parameters.

FASTOO_PAYOUT_NOT_READY

The requested Fastoo payout route is unavailable. Contact your account manager to confirm supported currencies and route activation. Inspect the returned payment status and error_code before creating a replacement. Invalid destination fields are request validation failures. See Fastoo troubleshooting for client integration checks.

PAYMENT_CREATE_OUTCOME_UNKNOWN

The creation response could not be verified. The request may already have created a payment. Check the original order, payment status and webhooks, or contact support before submitting a replacement. Keep the original merchant_reference and any returned payment ID; reusing a reference alone does not prove that a repeat is safe.

TEAM_BALANCE_FREEZE_TIMEOUT

This code can appear in a failed payment response or notification when creation exceeded a processing deadline. Check the original payment and contact support before initiating a replacement. A failure message alone does not establish that repeating a financial request is safe.

Authentication Errors

INVALID_API_KEY


HTTP Status	401
Message	API key not found or invalid
Cause	The provided API key is incorrect, expired, or doesn’t exist
Solution	Verify you’re using the correct API key provided by your LuxCore account manager. Ensure you’re using the correct key for the environment (`qp_test_sk_` or `qp_prod_sk_`).

{
  "statusCode": 401,
  "message": "API key not found or invalid",
  "error_code": "INVALID_API_KEY"
}

MISSING_API_KEY


HTTP Status	401
Message	API key is required
Cause	No `X-API-Key` header was provided
Solution	Include the `X-API-Key` header in your request

INSUFFICIENT_SCOPES


HTTP Status	403
Message	API key lacks required scope:
Cause	Your API key doesn’t have permission for this operation
Solution	Contact your LuxCore account manager to request additional scopes for your API key

Payment Errors

INSUFFICIENT_BALANCE


HTTP Status	400
Message	Insufficient balance for withdrawal
Cause	Your merchant balance is too low for the requested withdrawal
Solution	Check your balance via the Balance API. Contact support to confirm an approved funding route.

{
  "statusCode": 400,
  "message": "Insufficient balance for withdrawal",
  "error_code": "INSUFFICIENT_BALANCE"
}

MISSING_REQUISITES


HTTP Status	400
Message	No available requisites for this operation
Cause	No payment route is currently available for the requested currency and amount
Solution	Check existing payment outcomes first. Contact support to confirm route availability for your currency and amount before creating a replacement.

{
  "transaction_id": "pay_1761290149387_6149e9c2",
  "status": "failed",
  "amount": 200000,
  "currency": "ARS",
  "method": "bank_transfer",
  "type": "deposit",
  "merchant_reference": "fb384323-a356-4877-b9ff-9de8d0a3c126",
  "created_at": "2025-10-24T07:15:49.387Z",
  "error_code": "MISSING_REQUISITES",
  "error_message": "No available requisites for this operation"
}

NO_AVAILABLE_REQUISITES


HTTP Status	400
Message	No available requisites for this operation
Cause	The requested payment route is temporarily unavailable.
Solution	Check the original payment and contact support to confirm route availability.

INVALID_METHOD


HTTP Status	400
Message	Payment method is not configured or inactive
Cause	The requested payment method is not enabled for your merchant account, not supported for this currency, or has been deactivated
Solution	Contact support to enable the payment method. Verify the method is supported for your target currency and region.

{
  "statusCode": 400,
  "message": "Payment method 'bank_transfer' is not configured for currency USD",
  "error_code": "INVALID_METHOD"
}

INVALID_WITHDRAWAL_DATA


HTTP Status	400
Message	Invalid withdrawal data provided
Cause	The `payout` object contains invalid or incomplete data (e.g., invalid bank account format, missing recipient name, unsupported bank code)
Solution	Verify all payout fields: `recipient_name` (required), `bank_account` (valid format for country), `bank_code` (valid bank identifier). Check country-specific validation rules.

{
  "statusCode": 400,
  "message": "Invalid bank account format for ARS withdrawals",
  "error_code": "INVALID_WITHDRAWAL_DATA"
}

UNSUPPORTED_CURRENCY


HTTP Status	400
Message	Currency is not supported
Cause	The specified currency code is not supported by LuxCore or not enabled for your merchant account
Solution	Use a supported currency code. Contact support to enable additional currencies. Use a currency enabled for your merchant and payment route.

{
  "statusCode": 400,
  "message": "Currency 'EUR' is not supported for this merchant",
  "error_code": "UNSUPPORTED_CURRENCY"
}

WITHDRAWAL_NOT_SUPPORTED


HTTP Status	400
Message	Withdrawals are not supported for this payment method
Cause	The specified payment method only supports deposits, not withdrawals
Solution	Use a different payment method that supports withdrawals. Check method capabilities via the Methods API.

MERCHANT_REFERENCE_DUPLICATE


HTTP Status	200 (returns existing payment)
Message	N/A - existing payment is returned
Cause	A payment with this `merchant_reference` already exists. An existing active payment reference can return that payment; failed, expired or cancelled references can be reused.
Solution	Check the returned payment. After an uncertain result, reconcile the original outcome before creating a replacement, even with the same reference.

{
  "transaction_id": "pay_existing_123",
  "status": "pending",
  "merchant_reference": "order-12345",
  "created_at": "2025-10-24T07:10:00.000Z",
  "_note": "Existing payment returned due to duplicate merchant_reference"
}

Payment Status Errors

METHOD_NOT_AVAILABLE


HTTP Status	400
Message	Payment method '' is not available
Cause	The requested payment method is not enabled for your account or not supported for this operation
Solution	Contact support to enable the payment method, or use an alternative method

INVALID_AMOUNT


HTTP Status	400
Message	Amount must be between and
Cause	The payment amount is outside allowed limits
Solution	Ensure amount is within the method’s min/max limits. Check limits via the Methods API.

INVALID_CURRENCY


HTTP Status	400
Message	Currency '' is not supported
Cause	The specified currency is not valid or not enabled
Solution	Use a supported currency code (e.g., MXN, TRY, USD)

PAYMENT_NOT_FOUND


HTTP Status	404
Message	Payment not found
Cause	The payment ID doesn’t exist or doesn’t belong to your merchant
Solution	Verify the payment ID is correct

PAYMENT_ALREADY_PROCESSED


HTTP Status	400
Message	Payment cannot be cancelled in current status
Cause	The payment cannot be cancelled in its current state. Cancellation can be requested for pending/processing payments, subject to the returned outcome
Solution	Check the payment status. Completed, failed, or cancelled payments cannot be modified.

INVALID_CLABE


HTTP Status	400
Message	Invalid CLABE format
Cause	The bank account number (CLABE) is invalid
Solution	Verify the CLABE is 18 digits and passes checksum validation

INVALID_CVU


HTTP Status	400
Message	Invalid CVU format
Cause	The bank account number (CVU) is invalid
Solution	Verify the CVU is 22 digits and passes checksum validation

INVALID_BSB


HTTP Status	400
Message	Invalid BSB format
Cause	The BSB (Bank-State-Branch) number is invalid
Solution	Verify the BSB is 6 digits in `XXX-XXX` format (e.g., `062-000`). BSB must be a valid Australian bank branch code.

INVALID_PAYID


HTTP Status	400
Message	Invalid PayID identifier
Cause	The PayID value does not match the specified `payid_type` format
Solution	Verify the PayID format: `email` must be a valid email, `phone` must be in E.164 format (e.g., `+61412345678`), `abn` must be a valid 11-digit Australian Business Number.

{
  "statusCode": 400,
  "message": "Invalid PayID: expected valid email for payid_type 'email'",
  "error_code": "INVALID_PAYID"
}

PAYID_NOT_FOUND


HTTP Status	400
Message	PayID not registered
Cause	The PayID identifier is not registered in Australia’s New Payments Platform (NPP)
Solution	Verify the PayID with the recipient. The recipient must register their PayID through their Australian bank before receiving payments.

PAYOUT_DETAILS_REQUIRED


HTTP Status	400
Message	Payout details are required for withdrawal
Cause	Withdrawal request is missing required `payout` object
Solution	Include the destination format required by your route. Legacy bank/PayID payouts use their documented fields; typed Fastoo payouts use only `payout.fastooDestination` and must not be mixed with legacy destinations

Webhook Errors

WEBHOOK_NOT_FOUND


HTTP Status	404
Message	Webhook not found
Cause	The webhook ID doesn’t exist
Solution	Verify the webhook ID or list all webhooks to find the correct one

INVALID_WEBHOOK_URL


HTTP Status	400
Message	Invalid webhook URL
Cause	The URL is not a valid HTTPS endpoint
Solution	Use a publicly accessible HTTPS URL

WEBHOOK_DELIVERY_FAILED


HTTP Status	N/A (webhook event status)
Message	Webhook delivery failed after attempts
Cause	Your server returned a non-2xx response or timed out
Solution	Check your server logs. Ensure your endpoint returns 200 within 30 seconds.

Rate Limit Errors

RATE_LIMIT_EXCEEDED


HTTP Status	429
Message	Too Many Requests
Cause	You’ve exceeded the rate limit for this endpoint
Solution	Implement exponential backoff. Check the `Retry-After` header for wait time.

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error_code": "RATE_LIMIT_EXCEEDED"
}

Rate Limits:

Endpoint Type	Limit
Payment creation	5000 requests/minute (burst: 500/10sec)
Standard endpoints	100 requests/minute

Validation Errors

VALIDATION_ERROR


HTTP Status	400 or 422
Message	Varies based on field
Cause	Request body failed validation
Solution	Check the error message for specific field issues

{
  "statusCode": 400,
  "message": "amount must be a positive number; customer.email must be a valid email",
  "error_code": "Bad Request"
}

Server Errors

INTERNAL_ERROR


HTTP Status	500
Message	Internal server error
Cause	An unexpected error occurred on our servers
Solution	For a payment creation request, verify the original outcome before retrying. For reads, retry with bounded backoff; contact support if the issue persists.

SERVICE_UNAVAILABLE


HTTP Status	503
Message	Service Unavailable
Cause	The service is temporarily unavailable
Solution	For reads, retry later. For payment creation, verify the original outcome or contact support before submitting a replacement.

Error Handling Best Practices

Log All Errors

Log error responses with request IDs for debugging

Retry with Backoff

Use bounded backoff for reads; verify financial outcomes before repeating writes

Validate Before Sending

Validate inputs client-side before API calls

Handle Gracefully

Show user-friendly messages, not raw API errors

Example Error Handler

async function readPayment(paymentId, apiKey) {
  const response = await fetch(
    `https://api.lux-core.io/api/v1/payments/${encodeURIComponent(paymentId)}`,
    { headers: { "X-API-Key": apiKey }, signal: AbortSignal.timeout(30000) },
  );
  if (!response.ok) {
    const body = await response.json();
    const message = Array.isArray(body.message)
      ? body.message.join("; ")
      : body.message;
    throw new Error(
      `${body.error_code ?? body.error ?? response.status}: ${message}`,
    );
  }
  return response.json();
}
// Payment creation is a separate write operation. Do not automatically replay
// it after a timeout, connection loss or uncertain server response.

​Error Codes

​Error Response Format

​HTTP Status Codes

​Payment Error Codes Quick Reference

​FASTOO_PAYOUT_NOT_READY

​PAYMENT_CREATE_OUTCOME_UNKNOWN

​TEAM_BALANCE_FREEZE_TIMEOUT

​Authentication Errors

​INVALID_API_KEY

​MISSING_API_KEY

​INSUFFICIENT_SCOPES

​Payment Errors

​INSUFFICIENT_BALANCE

​MISSING_REQUISITES

​NO_AVAILABLE_REQUISITES

​INVALID_METHOD

​INVALID_WITHDRAWAL_DATA

​UNSUPPORTED_CURRENCY

​WITHDRAWAL_NOT_SUPPORTED

​MERCHANT_REFERENCE_DUPLICATE

​Payment Status Errors

​METHOD_NOT_AVAILABLE

​INVALID_AMOUNT

​INVALID_CURRENCY

​PAYMENT_NOT_FOUND

​PAYMENT_ALREADY_PROCESSED

​INVALID_CLABE

​INVALID_CVU

​INVALID_BSB

​INVALID_PAYID

​PAYID_NOT_FOUND

​PAYOUT_DETAILS_REQUIRED

​Webhook Errors

​WEBHOOK_NOT_FOUND

​INVALID_WEBHOOK_URL

​WEBHOOK_DELIVERY_FAILED

​Rate Limit Errors

​RATE_LIMIT_EXCEEDED

​Validation Errors

​VALIDATION_ERROR

​Server Errors

​INTERNAL_ERROR

​SERVICE_UNAVAILABLE

​Error Handling Best Practices

Log All Errors

Retry with Backoff

Validate Before Sending

Handle Gracefully

​Example Error Handler

Error Codes

Error Response Format

HTTP Status Codes

Payment Error Codes Quick Reference

FASTOO_PAYOUT_NOT_READY

PAYMENT_CREATE_OUTCOME_UNKNOWN

TEAM_BALANCE_FREEZE_TIMEOUT

Authentication Errors

INVALID_API_KEY

MISSING_API_KEY

INSUFFICIENT_SCOPES

Payment Errors

INSUFFICIENT_BALANCE

MISSING_REQUISITES

NO_AVAILABLE_REQUISITES

INVALID_METHOD

INVALID_WITHDRAWAL_DATA

UNSUPPORTED_CURRENCY

WITHDRAWAL_NOT_SUPPORTED

MERCHANT_REFERENCE_DUPLICATE

Payment Status Errors

METHOD_NOT_AVAILABLE

INVALID_AMOUNT

INVALID_CURRENCY

PAYMENT_NOT_FOUND

PAYMENT_ALREADY_PROCESSED

INVALID_CLABE

INVALID_CVU

INVALID_BSB

INVALID_PAYID

PAYID_NOT_FOUND

PAYOUT_DETAILS_REQUIRED

Webhook Errors

WEBHOOK_NOT_FOUND

INVALID_WEBHOOK_URL

WEBHOOK_DELIVERY_FAILED

Rate Limit Errors

RATE_LIMIT_EXCEEDED

Validation Errors

VALIDATION_ERROR

Server Errors

INTERNAL_ERROR

SERVICE_UNAVAILABLE

Error Handling Best Practices

Example Error Handler