# 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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](./error-codes.md).

> 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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](../getting-started/rate-limits.md).

---

## 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "success": false,
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "Service request timed out"
  }
}
```

---

## Status Code Quick Reference

| Code | Status | Meaning | Action |
|------|--------|---------|--------|
| **200** | OK | Success | Continue |
| **201** | Created | Resource created | Continue |
| **400** | Bad Request | Invalid request | Fix request |
| **401** | Unauthorized | Auth required | Check credentials |
| **402** | Payment Required | Card declined (`/public/transaction`) | See `ResponseCode`; do not retry unchanged |
| **403** | Forbidden | No permission, or service not on the tenant's plan | Check permissions / plan |
| **404** | Not Found | Resource missing | Check ID |
| **409** | Conflict | Duplicate/conflict | Check uniqueness |
| **422** | Unprocessable | Idempotency reuse, limit exceeded | Fix request |
| **429** | Too Many Requests | Rate limited | Retry with backoff |
| **500** | Internal Error | Server error | Retry or contact support |
| **502** | Bad Gateway | Gateway error | Retry |
| **503** | Service Unavailable | Temp unavailable | Retry later |
| **504** | Gateway Timeout | Timeout | Retry |

---

## Next Steps

- [Error codes →](./error-codes.md)
- [Error handling guide →](../getting-started/errors.md)
- [All endpoints →](./endpoints.md)

---

**Need help?** Contact support@auxcore.net