Rate limits

WorkOS APIs are rate limited to ensure that they are fast for everyone. If you find yourself getting 429 errors, double check your integration to make sure you aren’t making unnecessary requests.

When a request exceeds its rate limit, WorkOS returns a 429 Too Many Requests response. For limits enforced at the WorkOS edge, the JSON response body has this shape:

{
  "code": "too_many_requests",
  "message": "..."
}

The code is stable, while message is a human-readable explanation that may change. Some endpoint-specific limits are enforced by the API origin and return a response with only a human-readable message. For example, the GET /directory_users per-directory limit uses this response shape:

{
  "message": "..."
}

Use the HTTP status code instead of matching an exact message.

Origin responses include an x-request-id header.

When you receive a 429 response, use exponential backoff and randomize each delay to prevent synchronized retries. Increase the delay after each response, limit the total number of retries, and do not continuously retry while waiting. Cap the delay at the published rate-limit window. If you cannot track your request timestamps, wait one full window before retrying. Limits listed as per 60 seconds use a rolling 60-second window, so capacity becomes available as older requests leave the window.

This rate limit applies to all environments, staging and production. Exceptions to the general rate limit are listed below.

Authenticated API requests are counted per API key, not per source IP address. Spreading requests across multiple IP addresses does not increase your effective limit.

Rate limiting for AuthKit APIs are enforced on a per environment basis.