Skip to main content
Prowler’s Okta Provider manages API rate limits with two complementary controls:
  • Request throttling (proactive): Prowler paces outbound requests through a shared limiter so scans stay under Okta’s rate limits and rarely trigger a rate-limit response in the first place.
  • Retries (reactive): When Okta still returns a rate-limit response (HTTP 429), the official Okta Python SDK reads the X-Rate-Limit-Reset header and waits until the window resets before retrying. This acts as a safety net for occasional bursts.
Both controls are configurable through the configuration file or command line flags.

​
Request Throttling (Requests per Second)

Throttling is the primary control for avoiding rate limits. Prowler limits the aggregate number of Okta API requests per second across every service in a scan.

​
Using the Command Line Flag

prowler okta --okta-requests-per-second 4
Set the value to 0 to disable throttling.

​
Using the Configuration File

okta:
  # Maximum aggregate Okta API requests per second. Default: 4. Set to 0 to disable.
  okta_requests_per_second: 4
Okta enforces rate limits per endpoint, so this single global cap is a deliberately simple control. Lower the value if scans still hit limits on large organizations; raise it to scan faster when the organization has generous limits.

​
Retries

Retries cover the cases throttling does not prevent, such as short bursts or per-endpoint limits lower than the global cap.

​
Using the Command Line Flag

prowler okta --okta-retries-max-attempts 8

​
Using the Configuration File

okta:
  # Maximum retries on HTTP 429. Default: 5.
  okta_max_retries: 8
  # Per-request timeout in seconds. Default: 300.
  okta_request_timeout: 300
The command line flags override the configuration file values.

​
How It Works

  • Automatic detection: The Okta SDK retries the retryable statuses 429, 503, and 504.
  • Reset-aware backoff: On a 429 response the SDK sleeps until the X-Rate-Limit-Reset window before each retry, rather than using a fixed delay.
  • Bounded attempts: okta_max_retries caps how many times a single request is retried. The Okta SDK default is 2, which is often too low for large organizations, so Prowler defaults to 5.

​
Request Timeout

The okta_request_timeout setting plays a dual role in the Okta SDK:
  • It is the per-request socket timeout, bounding how long a single HTTP call can hang.
  • It is also the total wall-clock budget for the whole retry-and-backoff loop of one request.
For this reason, the value defaults to 300 seconds rather than 0 (no timeout). A value of 0 leaves hung connections unbounded, while a value that is too low cuts the rate-limit waits short and reintroduces the errors. As a guideline, keep okta_request_timeout greater than or equal to okta_max_retries multiplied by 60 when raising the retry count, because Okta reset windows are typically up to one minute.

​
Error Example Handled

Okta HTTP 429: Too Many Requests. Hit rate limit. Retry request in 42 seconds.

​
Validation

​
Debug Logging

To confirm that throttling and retries are active, run a scan with debug logging: 
prowler okta --okta-requests-per-second 4 --log-level DEBUG --log-file debuglogs.txt

​
Check the Messages

grep -i "throttling\|rate limit\|retry" debuglogs.txt

​
Expected Output

When throttling is enabled, Prowler logs the configured rate at startup: 
Okta request throttling enabled at 4 req/s
If a rate limit is still hit, the SDK logs the backoff: 
Hit rate limit. Retry request in 42 seconds.

​
Troubleshooting

If scans continue to hit rate limits:
  1. Lower --okta-requests-per-second so requests are paced more conservatively.
  2. Raise --okta-retries-max-attempts (and keep okta_request_timeout proportionally large) so the safety net absorbs more bursts.
  3. Review the rate-limit allocation for the Okta organization and request an increase if needed.
  4. Verify throttling and retry behavior with debug logging.

​
Official References