Skip to navigation

API limits and errors

The API applies both request limits and file-submission quotas. Check both when planning uploads: staying below a daily quota does not avoid an hourly limit.

Production limits

These limits apply to transcription submissions at https://api.sofer.ai:

Operation or quotaLimitShared byReset
Rate-limited transcription and batch API operations5 requests per minuteCalls using the same API keyStart of the next UTC minute
Individual v1 transcriptions: hourly quota50 files per hourAll API keys on the same accountStart of the next UTC hour
Individual v1 transcriptions: daily quota300 files per dayAll API keys on the same accountMidnight UTC
Standard batch transcriptions: daily quota5,000 files per dayAll API keys on the same accountMidnight UTC
Standard batch manifest1,000 audio URLs per manifestEach uploaded JSON or JSONL manifestPer manifest; split larger collections
Express batch10 audio sources per batchEach express batch requestPer request; split larger batches

Limits can differ in other API environments or under a custom configuration. The active limit reported in an error response takes precedence over this table. Contact support@sofer.ai to discuss higher-volume usage.

Support can configure custom hourly and daily individual v1 file allowances for a specific account. A custom allowance is shared across that account’s API keys in the same environment. The 429 response reports the effective account limit. Request-per-minute limits and standard-batch quotas still apply separately.

The request counter includes rate-limited operations such as creating a transcription, uploading or importing a batch manifest, creating a batch, and listing batch files or transcriptions. These calls share the same per-key minute allowance. Other endpoints may have their own request or concurrency limits.

How file quotas are counted

File quotas count submissions, not audio minutes. A file that was accepted and later failed still counts toward its submission quota. The individual v1 quotas apply to files submitted through Create Transcription with model: "v1". Both its hourly and daily quotas must have allowance remaining.

File quotas are shared across your account’s API keys in the same environment. Using another key on that account does not provide a fresh file allowance. Request limits are counted per API key. API balance and audio-duration billing are separate from these submission quotas.

Quota windows follow UTC clock boundaries, not rolling intervals. For example, the hour from 14:00:00Z through 14:59:59Z resets at 15:00:00Z, and the day resets at 00:00:00Z. Hourly and daily resets do not depend on when you started uploading. Waiting 60 seconds between files does not clear an exhausted hourly or daily quota.

Example: 200 individual files in one day

Submitting one file every 60 seconds can attempt 60 files in an hour, exceeding the 50-file hourly quota even though 200 files is below the daily allowance. Pause after 50 accepted files until the next UTC hour. Alternatively, spacing submissions by 90 seconds attempts about 40 per hour and leaves some headroom. Include submissions from other scripts or API keys on your account in that count, and keep the daily quota in your scheduler too.

Submitting a large collection

For large collections, use standard batch processing. Standard batches use their own daily file quota, separate from individual v1 submissions. For v1, standard processing costs 1.00peraudiohour∗∗,comparedwith∗∗1.00 per audio hour**, compared with **1.50 for individual submissions or express batches, and processes within 24 hours.

For example, split 2,000 audio URLs into two manifests of at most 1,000 items. Upload each manifest, then create a standard batch with its batch_file_id. Uploading the manifest and creating the batch each use a request from the per-minute allowance. Files count toward the standard-batch daily quota when the batch is accepted for processing.

The per-manifest size limit and daily batch quota apply together. A batch quota error reports how many files you requested and how many can still be accepted that UTC day. Exceeding a per-manifest or express-batch size limit returns a validation error; waiting for a quota reset will not make an oversized request fit.

Read the error and reset headers

An HTTP 429 can report an exhausted request quota, file quota, or concurrency limit. For window-based quotas, the response explains which quota, its active limit, and when it resets. The error body is a JSON string. For example, an individual daily quota response includes:

"Single-request v1 daily limit exceeded for this user. Accepted in the current UTC day: 300 files. Limit: 300 files per UTC day. Remaining: 0 files. This quota counts submitted files, including failed jobs, not audio minutes. Resets at 2026-11-13T00:00:00Z. Retry after 3600 seconds."
HeaderMeaning
Retry-AfterSeconds until the rejecting quota window resets
X-RateLimit-LimitActive maximum requests or files in that window
X-RateLimit-RemainingRequests or files still available in that window
X-RateLimit-ResetReset time as a Unix timestamp, in seconds
X-RateLimit-Policyapi_minute, individual_v1_hourly, individual_v1_daily, or standard_batch_daily

Wait until the indicated reset before retrying the rejected operation. If both individual-file quotas are exhausted, the response reports the daily quota, which resets later. An hourly reset will not restore an exhausted daily allowance. Concurrency throttles may not have a fixed reset time or these reset headers; read their response body for the reason.

Handle a quota error in Python

Update the Python client to a version generated from this API definition to retain the explanation on RateLimitError.body. Older client versions may discard it.

The client normally retries retryable HTTP responses. Disable automatic retries when you want to handle a quota explicitly, rather than retrying a daily quota that will not reset soon:

from soferai import SoferAI
from soferai.transcribe.errors import RateLimitError
client = SoferAI(api_key="YOUR_API_KEY")
try:
client.transcribe.create_transcription(
audio_url="https://example.com/audio.mp3",
info={"model": "v1"},
request_options={"max_retries": 0},
)
except RateLimitError as error:
print(error.body)
headers = error.headers or {}
print(headers.get("retry-after"))
print(headers.get("x-ratelimit-policy"))

If a daily or hourly individual-file quota is exhausted, wait for its reset or use the batch endpoint. For a batch larger than the remaining daily allowance, reduce the batch size or wait for the next UTC day. A batch larger than the entire daily limit must be split even after the quota resets.