Skip to main content

​
Limits

NextKS uses dual-level rate limiting — per API key and per organization — so a single runaway integration doesn’t block others.

​
Per API key

MetricValue
Burst10 requests in 5 seconds
Sustained~2 requests/second

​
Per organization (tenant)

MetricValue
Burst50 requests in 10 seconds
Sustained~5 requests/second

​
Other limits

LimitValue
Recipients per request50 email addresses
Message length4000 characters
When a rate limit is exceeded, the API returns: 
{
  "status": "error",
  "details": "Per-key rate limit exceeded (10 burst / 2 per second)"
}
HTTP status: 429 Too Many Requests Header: Retry-After: 1 The details message indicates which limit was hit (per-key or organization).

​
Idempotency

To safely retry requests without sending duplicate notifications, include an Idempotency-Key header: 
curl -X POST https://app.nextks.com/api/notify \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deploy-v2.4.1-notify-20260213" \
  -d '{ ... }'
  • If the same key is sent within 24 hours, the cached response is returned without re-processing
  • Keys are scoped per organization — different orgs can use the same key without conflict
  • Keys older than 24 hours are automatically cleaned up

​
Best practices

  • Batch recipients — Send to multiple users in a single request instead of making separate calls per user
  • Respect Retry-After — Wait the indicated number of seconds before retrying
  • Use idempotency keys — Include an Idempotency-Key header when retrying failed requests to prevent duplicates
  • Use callbacks — For interactive notifications, use callback_url instead of polling the status endpoint repeatedly
  • Cache responses — Status endpoint results can be cached for a few seconds to avoid unnecessary calls