Error Codes Reference

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

Error Response Format

All errors follow this structure:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "field": "fieldName",
    "details": {
      "additionalInfo": "value"
    }
  }
}

Authentication Errors (401)

Code	Message	Solution
`UNAUTHORIZED`	Invalid or expired token	Refresh your token by logging in again
`TOKEN_EXPIRED`	Token has expired	Get a new token via `/auth/login`
`TOKEN_INVALID`	Token format is invalid	Check token format and try again
`TENANT_REQUIRED`	X-Tenant-ID header required	Include `X-Tenant-ID` header
`TENANT_NOT_FOUND`	Tenant not found	Verify tenant ID is correct
`INVALID_CREDENTIALS`	Invalid email or password	Check login credentials

Authorization Errors (403)

Code	Message	Solution
`FORBIDDEN`	Insufficient permissions	Check API key permissions
`MERCHANT_NOT_AUTHORIZED`	Access to merchant denied	Verify merchant access rights
`RESOURCE_ACCESS_DENIED`	Cannot access this resource	Check resource ownership
`PERMISSION_DENIED`	Missing required permission	Request appropriate permissions

Validation Errors (400, 422)

Code	Message	Solution
`VALIDATION_ERROR`	Field validation failed	Fix the invalid field
`REQUIRED_FIELD_MISSING`	Required field missing	Provide all required fields
`INVALID_AMOUNT`	Amount invalid or negative	Provide valid positive amount
`INVALID_EMAIL`	Email format invalid	Provide valid email address
`INVALID_PHONE`	Phone format invalid	Provide valid phone number
`INVALID_DATE`	Date format invalid	Use ISO 8601 format (YYYY-MM-DD)
`INVALID_CURRENCY`	Currency code invalid	Use valid ISO 4217 code (USD, EUR, etc.)
`INVALID_CARD_NUMBER`	Card number invalid	Verify card number is correct
`INVALID_CVV`	CVV invalid	Provide 3-4 digit CVV
`INVALID_EXPIRY`	Expiry date invalid	Use MM/YYYY format
`CARD_EXPIRED`	Card has expired	Use non-expired card

Resource Errors (404)

Code	Message	Solution
`NOT_FOUND`	Resource not found	Verify resource ID exists
`TRANSACTION_NOT_FOUND`	Transaction not found	Check transaction ID
`MERCHANT_NOT_FOUND`	Merchant not found	Verify merchant ID
`CUSTOMER_NOT_FOUND`	Customer not found	Check customer ID
`INVOICE_NOT_FOUND`	Invoice not found	Verify invoice ID
`SUBSCRIPTION_NOT_FOUND`	Subscription not found	Check subscription ID

Conflict Errors (409)

Code	Message	Solution
`RESOURCE_CONFLICT`	Resource already exists	Use different identifier
`DUPLICATE_TRANSACTION`	Duplicate transaction	Check for existing transaction
`ALREADY_VOIDED`	Transaction already voided	Cannot void twice
`ALREADY_REFUNDED`	Fully refunded	No refund amount remaining
`ALREADY_CAPTURED`	Already captured	Cannot capture twice

Payment Errors

Transaction Declined

Code	Message	Solution
`TRANSACTION_DECLINED`	Transaction declined	See decline reason in response
`INSUFFICIENT_FUNDS`	Insufficient funds	Customer needs to add funds
`CARD_DECLINED`	Card declined	Try different card
`INVALID_CARD`	Card invalid	Verify card details
`CARD_NOT_SUPPORTED`	Card type not supported	Use supported card brand
`EXCEEDS_LIMIT`	Exceeds transaction limit	Reduce amount or contact support

AVS/CVV Errors

Code	Message	Solution
`AVS_MISMATCH`	AVS check failed	Verify billing address
`CVV_MISMATCH`	CVV check failed	Verify CVV code
`AVS_CVV_MISMATCH`	AVS and CVV failed	Verify address and CVV

Gateway Errors

Code	Message	Solution
`GATEWAY_ERROR`	Payment gateway error	Retry or contact support
`GATEWAY_TIMEOUT`	Gateway timeout	Retry request
`GATEWAY_UNAVAILABLE`	Gateway unavailable	Try again later

Business Logic Errors

Refunds

Code	Message	Solution
`NOT_REFUNDABLE`	Transaction not refundable	Check transaction status
`REFUND_AMOUNT_EXCEEDS`	Refund exceeds available	Reduce refund amount
`REFUND_DECLINED`	Refund declined by processor	See decline reason

Subscriptions

Code	Message	Solution
`SUBSCRIPTION_INACTIVE`	Subscription not active	Check subscription status
`ALREADY_PAUSED`	Subscription already paused	Resume before pausing again
`ALREADY_CANCELLED`	Subscription already cancelled	Cannot modify cancelled subscription

Invoices

Code	Message	Solution
`INVOICE_ALREADY_PAID`	Invoice already paid	Cannot modify paid invoice
`INVOICE_CANCELLED`	Invoice cancelled	Cannot pay cancelled invoice
`PAYMENT_EXCEEDS_DUE`	Payment exceeds amount due	Reduce payment amount

Rate Limiting Errors (429)

Code	Message	Solution
`RATE_LIMIT_EXCEEDED`	Too many requests	Wait and retry with backoff
`DAILY_LIMIT_EXCEEDED`	Daily limit reached	Wait until reset

Response includes retry information:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "retryAfter": 60,
      "limit": 100,
      "remaining": 0,
      "resetAt": "2026-01-28T13:00:00Z"
    }
  }
}

Server Errors (500)

Code	Message	Solution
`INTERNAL_ERROR`	Internal server error	Retry or contact support
`SERVICE_UNAVAILABLE`	Service temporarily unavailable	Retry with backoff
`DATABASE_ERROR`	Database error	Contact support

Decline Codes (Payment Processor)

These codes appear in the declineCode field when transactions are declined:

Code	Reason	Action
`insufficient_funds`	Insufficient funds	Customer needs to add funds
`card_declined`	Generic decline	Try different card
`invalid_account`	Invalid account number	Verify card number
`invalid_expiry`	Invalid expiry date	Check expiration
`cvv_failure`	CVV mismatch	Verify CVV
`avs_failure`	AVS mismatch	Verify address
`fraud_suspected`	Suspected fraud	Contact customer
`lost_stolen`	Lost or stolen card	Use different card
`expired_card`	Card expired	Use non-expired card
`restricted_card`	Card restricted	Contact card issuer
`exceeds_limit`	Exceeds card limit	Reduce amount
`do_not_honor`	Do not honor	Contact issuer
`call_issuer`	Call issuer	Customer should call bank

ACH Decline Codes

Code	Description	Action
`R01`	Insufficient funds	Customer needs funds
`R02`	Account closed	Get new account info
`R03`	No account found	Verify account number
`R04`	Invalid account number	Check routing/account
`R05`	Unauthorized debit	Customer must authorize
`R07`	Authorization revoked	Get new authorization
`R10`	Not authorized	Customer needs to authorize
`R29`	Corporate action	Contact customer

Error Handling Best Practices

Retryable Errors

These errors should be retried:

GATEWAY_TIMEOUT
GATEWAY_UNAVAILABLE
SERVICE_UNAVAILABLE
RATE_LIMIT_EXCEEDED
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
TRANSACTION_DECLINED

Fix the issue first, then retry.

Testing Error Scenarios

Test Card Numbers for Errors

Card Number	Result
4000000000000002	Declined
4000000000000127	CVV mismatch
4000000000000119	Expired card
4000000000000101	Fraud

Test API Errors

# Test validation error
curl -X POST https://dev.auxcore.net/api/v1/transactions \
  -d '{"amount": -100}'  # Invalid amount

# Test not found error
curl https://dev.auxcore.net/api/v1/transactions/invalid_id

# Test unauthorized error
curl https://dev.auxcore.net/api/v1/transactions \
  -H "Authorization: Bearer invalid_token"

Next Steps

Need help? Contact support@auxvault.com