Error Handling

Last updated: Phase 8.5

Error Envelope

All ValidonX API errors return a structured JSON envelope:

{
  "error": {
    "code": "DOMAIN.IDENTIFIER",
    "message": "Human-readable description of what went wrong",
    "type": "domain",
    "status": 404,
    "details": {}
  },
  "meta": {
    "request_id": "uuid",
    "api_version": "1"
  }
}

Fields

Field	Type	Description
error.code	string	Machine-readable error code (e.g., LICENSE.NOT_FOUND)
error.message	string	Human-readable message safe to display to users
error.type	string	Error domain (derived from code prefix)
error.status	integer	HTTP status code
error.details	object	Additional context (varies by error)
meta.request_id	string	Unique request ID for support tickets
meta.api_version	string	Always "1"

Using error.code

The error.code field is the primary mechanism for programmatic error handling:

try {
  const response = await fetch('/api/v1/integration/licenses/key/validate', { ... })
  const data = await response.json()
  if (!response.ok) {
    switch (data.error.code) {
      case 'LICENSE.NOT_FOUND':
        // Handle missing license
        break
      case 'LICENSE.REVOKED':
        // Handle revoked license
        break
      case 'RATE_LIMIT.EXCEEDED':
        // Back off and retry
        break
      default:
        // Unknown error
        console.error(data.error.message)
    }
  }
} catch (e) {
  // Network error
}

Using meta.request_id

Every response includes a request_id in the meta block. When contacting support, include this ID for fast diagnosis:

Support ticket: "License validation failing for key VX-ACME-..."
Request ID: 3f2504e0-4f89-11d3-9a0c-0305e82c3301

You can also send your own X-Request-ID header — the backend will echo it back in meta.request_id.

Common Auth Errors

Code	HTTP	When
AUTH.INVALID_API_KEY	401	Missing, invalid, or revoked API key
AUTH.INVALID_CREDENTIALS	401	Wrong email or password on login
AUTH.UNAUTHENTICATED	401	Missing or invalid Bearer token
AUTH.INSUFFICIENT_PERMISSIONS	403	Token lacks required ability
TENANT.STATUS.SUSPENDED	403	Tenant is suspended
RATE_LIMIT.EXCEEDED	429	Too many requests

See Error Codes for the complete list.