Rate Limiting

Every API request passes through a per-organisation token-bucket rate limiter. Limits depend on your plan tier and scale up as you upgrade.

Current Limits

Rate limits are applied per API key, not per IP. Each key gets its own independent counter, and exhausting one scope (e.g. crud) does not affect another (analytics_events).

Rate Limit Exceeded Response

When you exceed the bucket, you receive an HTTP 429 with the standard JSON envelope, error code SML005, an RFC 6585 Retry-After header, and a structured details payload:

HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json

{
  "errors": [
    {
      "code": "SML005",
      "message": "Rate limit exceeded",
      "details": {
        "kind": "rate_limit_exceeded",
        "scope": "crud",
        "limitPerMin": 30,
        "retryAfterSeconds": 12
      }
    }
  ]
}

See API Errors → SML005 for the full response shape including the details.scope and details.limitPerMin fields.

Best Practices

1. Honour the Retry-After header. It carries the seconds until the bucket refills enough for one more request. Sleep at least that long before retrying — don’t guess.

2. Use bulk endpoints. POST /shortenedUrl/bulkSave accepts up to 30 records in one request, consuming a single token from the rate limiter instead of 30.

3. Cache responses locally. If you re-read the same link repeatedly, store the response and refresh only when your data changes.

4. Add jitter on top of Retry-After. Multiple workers retrying at exactly now + retryAfter causes a thundering herd. A 0–25% jitter on top of the header value smooths the second-attempt distribution.

5. Pick the right plan tier. If you’re hitting crud at 300 / min sustained, you’re past BUSINESS — talk to the Codelloy team about ENTERPRISE.

6. Distribute writes evenly across the minute. Cron jobs that mint links in nightly bursts hit the per-minute cap mid-burst; pace them or batch via bulkSave.