Rate Limits

Contract

Semarize signals retry timing with Retry-After when a response is accepted for async follow-up or when the request is rate limited. Some JSON bodies include retry_after_seconds. Your client should use those values instead of hard-coded retry intervals.

Workspace and run-creation limits can vary by plan, traffic profile, and operational conditions. Build clients around backoff and admission control rather than fixed quota assumptions.

429 handling

• Wait at least Retry-After seconds before retrying.
• If the JSON body includes retry_after_seconds, use it as the retry delay.
• Retry with the same Idempotency-Key when the rate-limited request was POST /v1/runs and you are retrying the same logical request.

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

{
  "error": "rate_limited",
  "retry_after_seconds": 10
}

Polling backoff

Polling is part of normal async run handling, but it should be bounded. Begin with Retry-After when present, then use exponential backoff with a maximum delay. Stop polling when status is succeeded, failed, or cancelled.

Batch execution

When evaluating many conversations, use a work queue with a limited number of active run creation workers and a separate poller for accepted runs. This prevents a burst of source records from becoming a burst of duplicate API calls.

• Persist source record id, Idempotency-Key, run_id, status, and next_poll_at.
• Use a concurrency limit per workspace or integration account.
• Move rate-limited work back into the queue with the advised delay.
• Prefer webhooks for high-volume terminal notifications when your architecture supports them.

Timeouts and retries

Network timeouts do not prove that Semarize failed to accept the request. For POST /v1/runs, retry the same logical request with the same Idempotency-Key. For reads, retry with ordinary exponential backoff.