Troubleshooting Guide

Last updated: Phase 8.5

Common Issues

"Invalid API key" (AUTH.INVALID_API_KEY, 401)

• Verify the X-API-Key header is present and correctly formatted
• Check the key hasn't been revoked in the Tenant Dashboard
• Ensure you're using the raw key (starts with vx_), not the key ID
• Keys are case-sensitive — copy-paste exactly

"Tenant is suspended" (TENANT.STATUS.SUSPENDED, 403)

• Your tenant has been suspended by an administrator
• Contact your ValidonX administrator to resolve the suspension
• All API calls will fail until the tenant is reactivated

"License not found" (LICENSE.NOT_FOUND, 404)

• Verify the license key is correct and belongs to your tenant
• License keys are case-sensitive
• The license may have been deleted — check the Tenant Dashboard

"Maximum activations reached" (ACTIVATION.LIMIT_EXCEEDED, 403)

• Your license has reached its activation limit
• Check error.details.current and error.details.limit in the response
• Deactivate unused instances via the Tenant Dashboard
• Contact your administrator to increase the limit

"Rate limit exceeded" (RATE_LIMIT.EXCEEDED, 429)

• You've exceeded 1,000 requests per hour
• Check the Retry-After header for when to retry
• Implement caching for license validation (recommended: 5-15 min TTL)
• Use exponential backoff for retries

"Validation failed" (VALIDATION.FAILED, 422)

• Check required fields in the request body
• Verify field types (e.g., quantity must be an integer >= 1)
• Check error.details for field-specific validation messages

500 Internal Server Error

• Include meta.request_id when contacting support
• Retry after a short delay (these are typically transient)
• If persistent, check the ValidonX status page

Getting Help

When contacting support, always include:

1. The meta.request_id from the error response
2. The error.code value
3. The HTTP status code
4. The request method and path
5. Timestamp of the error