Rate Limits

Last updated: Phase 8.5

Integration API

The Integration API (/api/v1/integration/*) enforces per-key rate limiting:

Setting	Default	Configurable
Requests per window	1,000	VALIDONX_API_RATE_LIMIT_REQUESTS
Window duration	3,600 seconds (1 hour)	VALIDONX_API_RATE_LIMIT_PERIOD

Rate limit key: api:{X-API-Key} (anonymous requests use api:anonymous).

Response Headers

Every Integration API response includes:

Header	Description
X-RateLimit-Limit	Maximum requests per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Unix timestamp when the window resets

When Exceeded

HTTP 429 Too Many Requests:

{
  "error": {
    "code": "RATE_LIMIT.EXCEEDED",
    "message": "Too many requests.",
    "status": 429,
    "type": "rate_limit",
    "details": {
      "limit": 1000,
      "reset": 3200
    }
  },
  "meta": {
    "request_id": "uuid",
    "api_version": "1"
  }
}

Additional headers on 429 responses:

Header	Description
Retry-After	Seconds until the limit resets
X-RateLimit-Remaining	0

Login Rate Limit

The login endpoint (POST /api/auth/login) has a separate throttle:

Setting	Value
Max attempts	5
Decay period	60 seconds

Exceeding returns 429 Too Many Requests.

Admin and Tenant APIs

The Admin API (/api/v1/admin/*) and Tenant API (/api/v1/tenant/*) do not currently enforce per-request rate limits beyond Laravel's default throttling. These APIs are authenticated and intended for dashboard use, not high-volume automation.

Best Practices

• Cache license validation results locally (recommended TTL: 5-15 minutes)
• Use exponential backoff when receiving 429 responses
• Monitor X-RateLimit-Remaining header to preemptively throttle
• Contact support if you need higher limits for your use case