Status Codes Reference#

Complete HTTP status code reference for the AuxCORE API.

Success Responses (2xx)#

200 OK#

Request succeeded.

Used for:

• GET requests
• Successful operations
• Data retrieval
• A payment that is accepted but not final (ACH pending) or needs a 3DS / hosted redirect (success: false, status: "pending")

Example:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440020",
    "status": "approved"
  }
}

201 Created#

Resource successfully created.

Used for:

• POST requests that create resources
• New subscriptions, invoices, API keys, webhook endpoints
• Refunds (POST /transactions/:id/refund returns 201 even when the processor declines, so check data.status)

Example:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440030",
    "invoiceNumber": "INV-2026-000042",
    "createdAt": "2026-01-28T12:00:00Z"
  }
}

Client Errors (4xx)#

400 Bad Request#

Invalid request format or parameters.

Common causes:

• Missing required fields
• Invalid JSON
• Invalid data types
• Invalid parameter values

Example:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Amount must be greater than 0"
  }
}

The message names the offending field. Other 400 codes include PCI_SCOPE_VIOLATION (raw card data not allowed), TENANT_REQUIRED and INVALID_IDEMPOTENCY_KEY. Void, refund and capture rule violations (already voided, already settled, amount too large) are also 400 VALIDATION_ERROR.

401 Unauthorized#

Authentication required or invalid credentials.

Common causes:

• Missing x-api-key header (Public API) — error: "API key required"
• Unknown, disabled or deactivated API key (Public API) — error: "API key validation failed"
• Missing or invalid JWT (Admin API)
• Expired token (TOKEN_EXPIRED) or malformed / revoked token (INVALID_TOKEN)
• API key sent to an admin route that rejects it (INVALID_API_KEY)

Example:

{
  "success": false,
  "error": "API key required",
  "message": "Please provide a valid API key in the x-api-key header or request body"
}

Admin routes return { "success": false, "error": { "code": "UNAUTHORIZED", "message": "..." } }.

402 Payment Required#

Card-level decline on Public API POST /api/v1/public/transaction. The request was valid but the issuer declined the charge.

Example:

{
  "success": false,
  "status": "declined",
  "status_code": 402,
  "message": "Insufficient funds",
  "data": {
    "TransactionId": "550e8400-e29b-41d4-a716-446655440020",
    "Status": "9",
    "ResponseCode": "202"
  }
}

ResponseCode is an NMI-style decline code (202 = insufficient funds). See Error Codes.

AuxCORE SDK routes (/api/v1/auxvault/*) return HTTP 200 with Status: 9 for declines instead of 402.

403 Forbidden#

Insufficient permissions.

Common causes:

• User role lacks the required permission
• API key type not allowed on the route (an SDK public key outside payment endpoints, or any API key on permission-guarded routes)
• SDK key without an allowed Origin
• Device suspended or not active (DEVICE_SUSPENDED, DEVICE_NOT_ACTIVE)
• The tenant's plan does not include the service (SERVICE_UNAVAILABLE, message Service <name> is not available for this tenant. Please upgrade your subscription.) — do not retry

Example:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Not authorized for this invoice operation"
  }
}

404 Not Found#

Resource doesn't exist.

Common causes:

• Invalid transaction ID, merchant ID or other resource ID
• Resource belongs to another merchant or tenant
• Wrong X-Tenant-ID on an Admin (JWT) route (TENANT_NOT_FOUND); /api/v1/public/* ignores X-Tenant-ID
• A feature that is switched off for the tenant (NOT_FOUND, Resource not found)
• Typo in endpoint URL, or a path that does not exist (for example /api/v1/public/rerun)

Example:

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction not found"
  }
}

409 Conflict#

Resource conflict or duplicate.

Common causes:

• Resource already exists (CONFLICT, EMAIL_IN_USE)
• Idempotent request still in progress (IDEMPOTENCY_REQUEST_IN_PROGRESS)
• Dispute no longer open (DISPUTE_NOT_OPEN)
• Field locked by the merchant's gateway (FIELD_LOCKED_BY_GATEWAY)

Example:

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "A resource with this identifier already exists"
  }
}

422 Unprocessable Entity#

Request format valid but semantically incorrect.

Common causes:

• Idempotency key reused with a different body (IDEMPOTENCY_KEY_REUSED)
• Transaction, device or WatchDog limit exceeded (LIMIT_EXCEEDED, WATCHDOG_LIMIT_EXCEEDED)
• Batch settlement rejected (SETTLEMENT_FAILED)
• Invalid device status transition

Example:

{
  "success": false,
  "error": {
    "code": "WATCHDOG_LIMIT_EXCEEDED",
    "message": "Transaction blocked by WatchDog volume limit"
  }
}

Most business-rule violations (such as voiding a settled transaction) return 400, not 422.

429 Too Many Requests#

Rate limit exceeded.

Common causes:

• Too many requests from one IP in the window (public auth and checkout endpoints: 30 per 15 minutes; OTP: 10 per hour)
• Gateway tier limit for the tenant, or 400 requests per minute for a signed-in user

Example:

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

The response carries Retry-After and RateLimit-Reset headers (seconds). The gateway's general limiter answers with the plain text Too many requests, please try again later. See Rate Limits.

Server Errors (5xx)#

500 Internal Server Error#

Unexpected server error.

Common causes:

• Server malfunction
• Unhandled exception
• A downstream service could not be reached ({ "error": "Service unavailable", "message": "..." })

Example:

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  }
}

502 Bad Gateway#

Gateway/proxy error.

Common causes:

• Payment gateway or processor returned an error
• The API gateway got an error talking to a downstream service (BAD_GATEWAY)
• Fee preview could not be computed (FEE_PREVIEW_FAILED)

Example:

{
  "success": false,
  "error": {
    "code": "GATEWAY_ERROR",
    "message": "Payment gateway error"
  }
}

503 Service Unavailable#

Service temporarily unavailable.

Common causes:

• A downstream service is down or restarting (SERVICE_UNAVAILABLE, Service is temporarily unavailable)
• The idempotency store is unavailable (IDEMPOTENCY_UNAVAILABLE)

A service that is not on the tenant's plan returns 403 SERVICE_UNAVAILABLE, not 503.

Example:

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service is temporarily unavailable"
  }
}

504 Gateway Timeout#

Request timeout.

Common causes:

• A downstream service did not answer in time

Example:

{
  "success": false,
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "Service request timed out"
  }
}

Status Code Quick Reference#

Next Steps#

• Error codes →
• Error handling guide →
• All endpoints →

Need help? Contact support@auxcore.net