Error Codes Reference#

Complete list of all error codes returned by the AuxCORE API.

Error Response Format#

Most services return this structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

There is no error.field or error.details object. Validation messages name the offending field in the message text.

Three variants exist:

• API-key failures on /api/v1/public/* return error as a plain string: { "success": false, "error": "API key validation failed", "message": "..." }. An unknown or deactivated key normally gets API key validation failed (the api-key service answers 401 and the gateway reports it as a validation failure); Invalid API key appears only when that service returns 200 without data.
• Legacy POST /api/v1/public/transaction failures use { "success": false, "status": "declined", "status_code": ..., "message": "...", "data": { ... } }.
• Some services (merchant gateways, settlement, batch payouts, devices) return { "success": false, "message": "..." } without an error object.

See the Error Handling guide for examples.

Authentication Errors (401)#

Tenant Errors (400, 404)#

Authorization Errors (403)#

SDK public keys (lpk_live_…) also receive 403 for Origin required, Origin not allowed and Insufficient permissions.

Device Session Reasons (200)#

GET /api/v1/device/session answers with 200 even when the device cannot be reused — the reason is
business state, not an error. See Check Device Session.

Validation Errors (400)#

There are no dedicated codes for individual fields (INVALID_EMAIL, INVALID_CARD_NUMBER, INVALID_CVV, INVALID_EXPIRY, CARD_EXPIRED and similar). All of these surface as VALIDATION_ERROR or as a declined transaction.

Resource Errors (404)#

Conflict Errors (409, 422)#

Void, refund and capture rule violations (already voided, already refunded, already captured, not capturable, amount too large) are not separate codes. They return 400 VALIDATION_ERROR with a descriptive message, described under Business Logic Errors below.

Payment Errors#

Transaction Declined#

A declined card sale on POST /api/v1/public/transaction returns HTTP 402 with Status: "9" and a numeric ResponseCode — there is no TRANSACTION_DECLINED, CARD_DECLINED or INSUFFICIENT_FUNDS error code. See Decline Codes below.

AVS/CVV Declines#

AVS and CVV rule failures are declines with an internal response code and message, not separate error codes:

Transaction Rules Declines#

A merchant's Transaction Rule with the Deny action declines the payment before it reaches the processor:

Gateway Errors#

Limit Errors#

Cash Payment Errors#

Business Logic Errors#

These all return 400 VALIDATION_ERROR (or 404 NOT_FOUND); match on the message text rather than a code.

Voids, Captures, Refunds#

A refund that the processor declines still returns 201 with data.status: "declined". Gateway declines are added to the Refund Decline Queue, but nothing retries them automatically — call POST /api/v1/refund-decline-queue/:id/retry or /process-retries (see Refund Queue).

Invoices#

Subscriptions#

Rate Limiting Errors (429)#

The gateway's general limiter answers with the plain-text body Too many requests, please try again later instead of JSON. Both include RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset (seconds) and Retry-After headers. See Rate Limits.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests from this IP. Try again later."
  }
}

Server Errors (5xx)#

If the gateway cannot reach a downstream service it returns 500 { "error": "Service unavailable", "message": "..." }.

Decline Codes (Response Codes)#

Declines are reported in ResponseCode / ResponseMessage using NMI-compatible numeric codes. Processor-native codes (for example TSYS 05) are normalized to these. 100 is approval.

Soft declines (retry may succeed) include the 26x and communication-error codes.

ACH Return Codes#

ACH returns are delivered by the transaction.returned webhook. The NACHA R-code appears in data.responseText.

Error Handling Best Practices#

Retryable Errors#

These errors should be retried:

• GATEWAY_TIMEOUT
• SERVICE_UNAVAILABLE (only with HTTP 503)
• RATE_LIMITED
• 500-level errors

Use exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (!isRetryable(error) || i === maxRetries - 1) {
        throw error;
      }
      await sleep(Math.min(1000 * Math.pow(2, i), 10000));
    }
  }
}

Non-Retryable Errors#

Don't retry these:

• VALIDATION_ERROR
• UNAUTHORIZED
• NOT_FOUND
• FORBIDDEN
• A 402 decline (Status: "9")

Fix the issue first, then retry.

Testing Error Scenarios#

Test Card Numbers for Errors#

Other decline test numbers are not documented here. Use the amounts and cards listed in Testing.

Test API Errors#

# Test validation error (Public API)
curl -X POST https://uat.auxcore.net/api/v1/public/transaction \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"Amount": -100, "pciToken": "pci_tok_9f2c4e7a1b3d"}'

# Test not found error (Public API)
curl https://uat.auxcore.net/api/v1/public/transaction/invalid_id \
  -H "x-api-key: YOUR_API_KEY"

# Test unauthorized error
curl https://uat.auxcore.net/api/v1/public/transaction-list \
  -H "x-api-key: invalid_key"

Next Steps#

• Error handling guide →
• All endpoints →
• Webhook events →

Need help? Contact support@auxcore.net