ValidonX API Error Codes

Every ValidonX API error returns a structured envelope with a dotted code (DOMAIN.CATEGORY), a human-readable message, and an HTTP status — this page catalogues every code by domain. Branch on error.code, not on the message text or HTTP status alone.

Per ADR-009: Error Taxonomy & Error Handling Last updated: 2026-07-06

Error Response Format

All errors follow the structured envelope format:

{
  "error": {
    "code": "DOMAIN.CATEGORY",
    "message": "Human-readable description",
    "type": "domain",
    "status": 401,
    "details": {}
  },
  "meta": {
    "request_id": "uuid",
    "api_version": "1"
  }
}

Error Code Reference

AUTH — Authentication & Authorization

Code	HTTP	Description
AUTH.INVALID_CREDENTIALS	401	Email or password is incorrect
AUTH.INVALID_API_KEY	401	Missing, invalid, or revoked API key
AUTH.API_KEY_REVOKED	401	API key has been revoked
AUTH.ACCOUNT_LOCKED	429	Account temporarily locked due to repeated failed login attempts
AUTH.UNAUTHENTICATED	401	No valid authentication token provided
AUTH.TOKEN.REQUIRED	401	No authentication provided
AUTH.TOKEN.INVALID_SCOPE	403	Token is missing a required scope
AUTH.API_KEY_NOT_FOUND	404	API key not found for this tenant
AUTH.FORBIDDEN	403	Authenticated but insufficient permissions
AUTH.INSUFFICIENT_PERMISSIONS	403	User lacks required role/ability
AUTH.VERIFICATION_FAILED	403	Invalid email verification link
AUTH.PASSWORD_RESET_FAILED	422	Invalid or expired password reset token

RATE_LIMIT — Rate Limiting

Code	HTTP	Description
RATE_LIMIT.EXCEEDED	429	Too many requests — check Retry-After header

TENANT — Tenant Resolution

Code	HTTP	Description
TENANT.NOT_FOUND	404	Tenant does not exist
TENANT.INVALID_STATE	403	Tenant is not in a valid state for this operation
TENANT.STATUS.SUSPENDED	403	Tenant is suspended
TENANT.RESOLUTION.REQUIRED	400	Multi-tenant user must specify X-Tenant-ID
TENANT.RESOLUTION.NO_TENANTS	403	User has no active tenants
TENANT.RESOLUTION.ACCESS_DENIED	403	User does not belong to the specified tenant

LICENSE — License Operations

Code	HTTP	Description
LICENSE.NOT_FOUND	404	License key does not exist
LICENSE.REVOKED	403	License has been revoked

ACTIVATION — Activation Operations

Code	HTTP	Description
ACTIVATION.INVALID	400	Invalid activation, or the license is not active
ACTIVATION.LIMIT_EXCEEDED	403	Maximum activations reached for this license

ENTITLEMENTS — Entitlement Operations

Code	HTTP	Description
ENTITLEMENTS.MISSING	403	Required entitlement not available on current plan
ENTITLEMENTS.LIMIT_EXCEEDED	403	Entitlement usage limit exceeded

BILLING — Billing & Subscription

Code	HTTP	Description
BILLING.SUBSCRIPTION_NOT_FOUND	404	Subscription does not exist
BILLING.SUBSCRIPTION_ALREADY_CANCELED	409	Subscription is already cancelled
BILLING.SUBSCRIPTION_STRIPE_ERROR	502	Stripe API error during subscription operation
BILLING.INVOICE_NOT_FOUND	404	Invoice does not exist
BILLING.REFUND_NOT_ALLOWED	422	Refund not allowed for this invoice
BILLING.PAYMENT_METHOD_NOT_FOUND	404	Payment method does not exist
BILLING.AUTH_FORBIDDEN	403	Insufficient billing role

ONBOARDING — Self-Service Onboarding

Code	HTTP	Description
ONBOARDING.PLAN_NOT_FOUND	404	Selected plan is not available
ONBOARDING.CHECKOUT_FAILED	502	Stripe Checkout session creation failed
ONBOARDING.PROVISIONING_FAILED	500	Tenant provisioning pipeline failed
ONBOARDING.STRIPE_CUSTOMER_FAILED	502	Stripe customer creation failed

CATALOG — Product Catalog

Code	HTTP	Description
CATALOG.INVALID_PRODUCT	422	Invalid product data
CATALOG.INVALID_PLAN	422	Invalid plan data
CATALOG.NOT_FOUND	404	Catalog item not found

SYSTEM — Internal Errors

Code	HTTP	Description
INTERNAL.ERROR	500	Unexpected internal error
SYSTEM.STRIPE_NOT_CONFIGURED	500	Stripe API keys not configured
VALIDATION.FAILED	422	Request validation failed (see details for field errors)