Rate limits

Limits are enforced per API key with a fixed 60-second window that resets at the boundary. The default is 60 requests per minute per key; higher Production limits can be negotiated.

Response headers

Every response includes the current rate-limit state.

When the limit is exceeded, the response is HTTP 429 with error.code = rate_limit_exceeded and a Retry-After header containing the wait time in seconds.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1782604860
Retry-After: 12

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded.",
    "request_id": "req_..."
  }
}

Public unauthenticated routes

Public routes have no API key and are limited to 20 requests per minute per client IP, using the same fixed window, headers, and 429 + Retry-After contract. This applies to application creation, status, and approval claim (POST /v1/partner-applications*) and to POST /v1/api-keys/bootstrap, reducing application spam and approval-token brute force.

Backoff guidance

• Honor Retry-After. Wait the stated number of seconds before retrying and do not hammer the endpoint.
• Use exponential backoff with jitter for repeated 429 and 5xx responses.
• Throttle proactively. Track X-RateLimit-Remaining and slow down before it reaches zero.
• Batch when possible. Use POST /events/batch for up to 500 events instead of many POST /events calls (Event API).
• Separate keys by workload. Because limits are per key, use different keys for high-volume ingestion and interactive calls.
• Retries are safe for supported idempotent operations. Events deduplicate by event_id; playback-token creation, license-request creation, and key rotation accept X-NU-Request-Id. Completed retries within 24 hours replay the original result; an in-progress duplicate returns 409 conflict.

Production rate-limit handling is part of the Production checklist.