Working with rate limits

The Zep API enforces rate limits on incoming requests. Rate limits are measured in requests per minute (RPM) and applied per account.

Your account entitlements set the normal RPM limit. See the Zep pricing page for plan details.

Zep can temporarily reduce the limit in these conditions:

• A Free account that exceeds its usage quota enters a 5 RPM penalty mode.
• Adaptive protection can reduce the limit during reranker pressure.

The response headers contain the active limit for the request.

Rate limit headers

Every response from the Zep API includes headers that describe your current rate limit state. Inspect these headers to monitor usage and pace your client before you hit the limit.

Reading rate limit headers from the SDK

The Zep SDKs do not return response headers from a normal method call. To read headers, use the SDK’s raw response accessor, which returns both the parsed response data and the raw HTTP response.

response = client.thread.with_raw_response.add_messages(
    thread_id="thread_123",
    messages=messages,
)
remaining = response.headers.get("x-ratelimit-remaining")
reset = response.headers.get("x-ratelimit-reset")
data = response.data

Handling 429 responses

When you exceed your rate limit, the Zep API returns HTTP 429 Too Many Requests. The SDK surfaces this as a typed error whose response headers include Retry-After, indicating how many seconds to wait before retrying.

Catch the error, read Retry-After, wait, and retry.

import time
from zep_cloud import ApiError
try:
    client.thread.add_messages(thread_id="thread_123", messages=messages)
except ApiError as err:
    if err.status_code == 429:
        retry_after = int(err.headers.get("retry-after", "1"))
        time.sleep(retry_after)
        # retry your call

Combine Retry-After with exponential backoff and jitter to avoid synchronized retries when many clients are throttled at the same time.

Pacing requests proactively

To avoid hitting 429 responses in the first place, use X-RateLimit-Remaining and X-RateLimit-Reset to pace your requests:

• If X-RateLimit-Remaining is approaching zero, slow your request rate or pause until the window resets.
• The current window ends at the Unix timestamp in X-RateLimit-Reset. After this time, a fresh allowance is available.

This is particularly useful for bulk operations, such as batch ingestion, where you control the cadence of outgoing requests.

Polling and webhooks

Every status request counts against the limit. A poll of graph.episode.get, batch.get, or a task status endpoint costs one request, the same as a write. During a processing delay, each poll returns the same unfinished state. A client that polls many tasks or batches in a tight loop can reach the account limit.

For episode completion, subscribe to the episode.processed webhook instead of polling. For batch completion, the ingest.batch.completed webhook covers succeeded runs, canceled runs, and partial runs that finish with canceled items. Zep does not send it for failed runs, or for partial runs that contain failed items. Poll batch.get to detect those two outcomes. When you must poll, use a fixed interval of several seconds. Increase the interval after each unfinished response.