Status Codes Reference

Complete HTTP status code reference for the AuxVault API.

Success Responses (2xx)

200 OK

Request succeeded.

Used for:

GET requests
Successful operations
Data retrieval

Example:

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123"
  }
}

201 Created

Resource successfully created.

Used for:

POST requests that create resources
New transactions
New subscriptions
New invoices

Example:

{
  "success": true,
  "data": {
    "invoiceId": "inv_abc123",
    "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": "Invalid request parameters",
    "field": "amount"
  }
}

401 Unauthorized

Authentication required or invalid credentials.

Common causes:

Missing Authorization header
Invalid or expired token
Missing X-Tenant-ID header

Example:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token"
  }
}

403 Forbidden

Insufficient permissions.

Common causes:

API key lacks required permissions
Accessing resource outside your tenant
Feature not enabled for your account

Example:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}

404 Not Found

Resource doesn't exist.

Common causes:

Invalid transaction ID
Invalid merchant ID
Invalid resource ID
Typo in endpoint URL

Example:

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

409 Conflict

Resource conflict or duplicate.

Common causes:

Duplicate transaction
Resource already exists
Conflicting operation

Example:

{
  "success": false,
  "error": {
    "code": "RESOURCE_CONFLICT",
    "message": "Transaction already exists"
  }
}

422 Unprocessable Entity

Request format valid but semantically incorrect.

Common causes:

Business rule violation
Invalid state transition
Validation failure

Example:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Cannot void settled transaction",
    "field": "status"
  }
}

429 Too Many Requests

Rate limit exceeded.

Common causes:

Too many requests in time window
Exceeded hourly limit
Exceeded daily limit

Example:

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

Server Errors (5xx)

500 Internal Server Error

Unexpected server error.

Common causes:

Server malfunction
Unhandled exception
Database error

Example:

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

502 Bad Gateway

Gateway/proxy error.

Common causes:

Payment gateway down
Service unavailable
Network error

Example:

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

503 Service Unavailable

Service temporarily unavailable.

Common causes:

Maintenance mode
Service overload
Deployment in progress

Example:

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

504 Gateway Timeout

Request timeout.

Common causes:

Payment gateway timeout
Slow network
Long-running operation

Example:

{
  "success": false,
  "error": {
    "code": "GATEWAY_TIMEOUT",
    "message": "Request timeout"
  }
}

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
403	Forbidden	No permission	Check permissions
404	Not Found	Resource missing	Check ID
409	Conflict	Duplicate/conflict	Check uniqueness
422	Unprocessable	Validation failed	Fix data
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

Need help? Contact support@auxvault.com