> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.sofer.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sofer.ai/_mcp/server.

# API limits and errors

> Understand API request and file quotas, error messages, and UTC reset times.

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 quota                                  | Limit                             | Shared by                            | Reset                                  |
| --------------------------------------------------- | --------------------------------- | ------------------------------------ | -------------------------------------- |
| Rate-limited transcription and batch API operations | **5 requests per minute**         | Calls using the same API key         | Start of the next UTC minute           |
| Individual v1 transcriptions: hourly quota          | **50 files per hour**             | All API keys on the same account     | Start of the next UTC hour             |
| Individual v1 transcriptions: daily quota           | **300 files per day**             | All API keys on the same account     | Midnight UTC                           |
| Standard batch transcriptions: daily quota          | **5,000 files per day**           | All API keys on the same account     | Midnight UTC                           |
| Standard batch manifest                             | **1,000 audio URLs per manifest** | Each uploaded JSON or JSONL manifest | Per manifest; split larger collections |
| Express batch                                       | **10 audio sources per batch**    | Each express batch request           | Per 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](mailto: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](/api-reference/transcribe/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](/api-reference/batch-transcribe/create-batch-transcription).
Standard batches use their own daily file quota, separate from individual v1
submissions. For v1, standard processing costs **$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](/api-reference/batch-transcribe/upload-batch-file), 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:

```json
"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."
```

| Header                  | Meaning                                                                                |
| ----------------------- | -------------------------------------------------------------------------------------- |
| `Retry-After`           | Seconds until the rejecting quota window resets                                        |
| `X-RateLimit-Limit`     | Active maximum requests or files in that window                                        |
| `X-RateLimit-Remaining` | Requests or files still available in that window                                       |
| `X-RateLimit-Reset`     | Reset time as a Unix timestamp, in seconds                                             |
| `X-RateLimit-Policy`    | `api_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:

```python
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.