Developer Docs•stable•Updated 2026-07-06

Rate Limits

Design Kadryn Gateway, direct ingest and webhook clients to handle throttling and backpressure safely.

Rate limits protect Kadryn, your workspace and upstream providers from uncontrolled traffic.

A rate limit can happen at several layers:

  • your application;
  • Kadryn API;
  • Kadryn Gateway;
  • provider route;
  • upstream AI provider;
  • webhook delivery destination.

How to handle rate limits

When a request is rate limited:

  1. do not retry immediately in a tight loop;
  2. use exponential backoff with jitter;
  3. preserve idempotency keys;
  4. preserve trace IDs and request group IDs;
  5. reduce concurrency if limits continue;
  6. move worker traffic through queues when possible.

Gateway rate limits

Gateway traffic can be limited by:

  • Kadryn workspace limits;
  • provider route limits;
  • upstream provider limits;
  • plan entitlements;
  • budget caps or policy enforcement.

A Gateway rate limit does not always mean Kadryn itself is the bottleneck. Check Logs & Traces to see whether the limit came from Kadryn or the provider.

Direct ingest rate limits

For ingestion workers:

  • batch events;
  • keep batches bounded;
  • retry only failed batches;
  • use stable idempotency keys;
  • avoid high-cardinality retry storms;
  • log accepted, rejected and retried counts.

Webhook destination limits

If your endpoint is slow or rate limited, Kadryn may retry, mark deliveries as retrying or eventually fail them.

Your endpoint should:

  • respond quickly;
  • perform heavy work asynchronously;
  • verify signatures before processing;
  • return a 2xx after accepting the event;
  • avoid long synchronous work.

Client retry policy

Recommended default:

txt
initial delay: 500 ms
max delay: 30 s
max attempts: 5
jitter: enabled
idempotency: required for writes

Do not use the same retry policy for permanent errors.

What not to retry

Do not retry without changing the request when the error is:

  • invalid API key;
  • missing permission;
  • invalid payload;
  • policy block;
  • missing provider key;
  • unsupported model;
  • malformed webhook signature.

Observability

Track:

  • request rate;
  • retry count;
  • error code;
  • final status;
  • latency;
  • request group ID;
  • trace ID;
  • idempotency key prefix or hash;
  • queue lag.

Do not log full secrets.

Related pages