Error Handling#

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

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required. Provide a Bearer token, auth cookie, or x-api-key header."
  }
}

{
  "success": false,
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Access token has expired. Please refresh your token."
  }
}

{
  "success": false,
  "error": {
    "code": "TENANT_REQUIRED",
    "message": "Tenant identification required. Provide X-Tenant-ID header or authenticate with a valid JWT."
  }
}

{
  "success": false,
  "error": {
    "code": "TENANT_NOT_FOUND",
    "message": "Tenant acme-prod not found"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email and password are required"
  }
}

{
  "success": false,
  "error": {
    "code": "PCI_SCOPE_VIOLATION",
    "message": "PublicAPI.transaction: raw card data is not permitted in this environment. Collect card data via the PCI iframe/SDK and submit a pciToken only."
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction with id 550e8400-e29b-41d4-a716-446655440020 not found"
  }
}

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Transaction already voided"
  }
}

{
  "success": false,
  "status": "declined",
  "status_code": 402,
  "message": "Insufficient funds",
  "data": {
    "TransactionId": "550e8400-e29b-41d4-a716-446655440021",
    "Status": "9",
    "Amount": 50.00,
    "ResponseCode": "202",
    "ResponseMessage": "Insufficient funds",
    "AvsResult": "N",
    "CvvResult": "M"
  }
}

{
  "success": false,
  "error": {
    "code": "GATEWAY_ERROR",
    "message": "CoinVoyage did not return a pay order"
  }
}

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

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "API key is not authorized for the requested merchant."
  }
}

const response = await fetch('https://app.auxcore.net/api/v1/public/transaction', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(transactionData)
});

if (response.status === 429) {
  const retryAfter = Number(response.headers.get('retry-after') || 60);
  await sleep(retryAfter * 1000);
  return retryRequest();
}

const result = await response.json();

if (response.status === 402 || result.status === 'declined') {
  // Card declined — show result.message to the payer, do not retry
  return { declined: true, code: result.data?.ResponseCode, message: result.message };
}

if (!response.ok) {
  // error is an object on most routes, a string on API-key failures
  const code = typeof result.error === 'string' ? result.error : result.error?.code;
  const message = result.message || result.error?.message || 'An error occurred';

  switch (code) {
    case 'TOKEN_EXPIRED':
      await refreshToken();
      return retryRequest();
    case 'VALIDATION_ERROR':
    case 'PCI_SCOPE_VIOLATION':
      console.error(`Fix the request: ${message}`);
      break;
    case 'GATEWAY_ERROR':
      return retryWithBackoff();
    default:
      console.error('API Error:', code, message);
  }
  throw new Error(message);
}

if (result.status === 'pending' && result.requires_action) {
  window.location.href = result.data.RedirectUrl;
}

return result.data;

import requests
import time

def process_payment(transaction_data, api_key):
    url = 'https://app.auxcore.net/api/v1/public/transaction'
    headers = {
        'x-api-key': api_key,
        'Content-Type': 'application/json'
    }

    response = requests.post(url, json=transaction_data, headers=headers)

    if response.status_code == 429:
        time.sleep(int(response.headers.get('Retry-After', 60)))
        return process_payment(transaction_data, api_key)

    result = response.json()

    if response.status_code == 402 or result.get('status') == 'declined':
        print(f"Transaction declined: {result.get('message')}")
        return None

    if not response.ok:
        error = result.get('error')
        code = error if isinstance(error, str) else (error or {}).get('code', 'UNKNOWN_ERROR')
        message = result.get('message') or (error or {}).get('message', 'An error occurred')
        if code == 'GATEWAY_ERROR':
            return retry_with_backoff(transaction_data, api_key)
        raise Exception(f"{code}: {message}")

    return result.get('data')

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Don't retry non-retryable errors
      if (!isRetryable(error)) throw error;
      
      // Wait with exponential backoff
      const delay = Math.min(1000 * Math.pow(2, i), 10000); // Max 10s
      await sleep(delay);
    }
  }
}

function isRetryable(error) {
  const retryableCodes = [
    'GATEWAY_ERROR',
    'SERVICE_UNAVAILABLE',
    'RATE_LIMITED'
  ];
  return retryableCodes.includes(error.code) || error.status >= 500;
}

curl -X POST https://app.auxcore.net/api/v1/transactions/sale \
  -H "Authorization: Bearer TOKEN" \
  -H "Idempotency-Key: 6f1c2e9a-4b7d-4e2a-9c1f-0a8b3d5e7f21" \
  -H "Content-Type: application/json" \
  -d '{"merchantId":"550e8400-e29b-41d4-a716-446655440000","amount":100.00,"paymentMethod":"card","pciToken":"pci_tok_..."}'

{
  "timestamp": "2026-01-28T12:34:56Z",
  "level": "error",
  "requestId": "req_abc123",
  "errorCode": "VALIDATION_ERROR",
  "errorMessage": "Invalid card number",
  "field": "card.number",
  "userId": "user_123",
  "action": "process_payment",
  "retryCount": 0
}