Rate limiting & idempotency

Per-tenant quotas, retry-safe writes, and how to read the rate-limit headers.

Per-tenant quotas

Each tenant gets a sliding-window RPS budget (default 30 RPS on paid tenants, 5 on free). The window is enforced per minute. Heavy batch endpoints (translation batch, scrape crawl) consume against a separate background budget so they don't starve interactive calls.

Reading rate-limit headers

Every response carries:

X-RateLimit-Limit — the bucket ceiling.
X-RateLimit-Remaining — credits left in this window.
X-RateLimit-Reset — seconds until the bucket refills.

On 429, retry after at least Retry-After seconds. The SDK does this automatically with capped exponential backoff.

Idempotency keys

Mutating endpoints accept an Idempotency-Key header. If Valienz sees the same key within 24 hours, it returns the original response — no duplicate side effect. Use a fresh UUIDv4 per logical operation.

curl -X POST https://api.valienz.io/v1/email/send \
  -H "Authorization: Bearer $VALIENZ_API_KEY" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Idempotency cache windows: 24h for most products, 7 days for billing/purchase endpoints.

Quota errors

Code	HTTP	Description	Resolution
E_QUOTA_EXCEEDED	429	Tenant exceeded its RPS or per-day budget.	Honor `Retry-After`, then back off exponentially. Upgrade the plan or contact support for a higher cap.
E_IDEMPOTENCY_KEY_REUSED	409	The same idempotency key was used for a different request body.	Use a unique key per logical operation. Reusing requires byte-identical bodies.