Limits and Quota

Overview

The IDParse API enforces two limits:

Per minute limit. It limits how many requests your account can send within 60 seconds.
Included scans. Your plan includes a fixed number of scans per calendar month. The usage is set back to 0 on the 1st of each month (UTC).

Both limits are checked for every extract request. A request must pass both checks.

Per Minute Limit

The per minute limit is a sliding window (the API counts the requests of the last 60 seconds). It belongs to your account, so all API keys of the account share it. Requests that reach the per minute limiter count, including quota calls and requests that fail later. Requests refused earlier (wrong key, maintenance) do not count.

When the limit is reached, the API answers with 429 and the error code rate_limited. Your per minute limit depends on your plan. The X-RateLimit-Limit header shows it.

Included Scans

Only a validated success ("success": true) uses one of your included scans. See What Is Charged.

By default the API makes a hard stop: when all included scans of the month are used, every further extract request gets 429 with the error code quota_exhausted until the next month begins. No extra cost can arise.

The quota endpoint shows the limit that applies to your account as effective_limit. For most accounts it is equal to the included scans.

Response Headers

Usage headers on answers of POST /v1/extract:

Header	Description
`X-IDParse-Scans-Included`	The scans that are included in your plan per month
`X-IDParse-Scans-Used`	The scans that are used in the current month, including the charge of this request
`X-IDParse-Scans-Remaining`	The included scans that are left, never below 0
`X-IDParse-Period-Ends`	The end of the current period in ISO 8601 format, UTC. It is the first day of the next calendar month, for example `2026-10-01T00:00:00Z`. The header is left out during the free trial, because its scans never start again
`Cache-Control`	`no-store`, so no cache keeps the answer

Important

The usage headers are a snapshot. The numbers are taken when the request is admitted and then corrected for the charge of this request. Requests that run in parallel can be included in the numbers. Cache-Control: no-store is present on every answer that passed the key check and the maintenance check. The four usage headers are present only when the monthly usage check returned a result. They can be missing on early rejections (401, 403, 503 maintenance), on 429 rate_limited, on 503 service_unavailable when the usage check itself failed, and for accounts without a monthly limit. Do not build logic that needs them on every answer. GET /v1/quota returns the current usage count at any time. The usage count can include scans that are still being processed. It cannot confirm whether one interrupted request was charged.

Other headers:

Header	Description
`X-Request-ID`	A unique identifier of the request, on every answer. Use it to match a request in your own logs
`X-RateLimit-Limit`	The number of requests your account can send per minute
`X-RateLimit-Remaining`	The requests that are left in the current 60-second window
`X-RateLimit-Reset`	Unix timestamp of the moment the current window ends
`Retry-After`	On `429` and `503` answers: the number of seconds to wait before retrying

Note

The X-RateLimit-* headers describe the per minute limit. There is one exception: on a 429 quota_exhausted answer they describe the monthly limit, and X-RateLimit-Reset is the start of the next month.

Exceeding Limits

When the per minute limit is reached, the API returns a 429 Too Many Requests response. Retry-After holds the seconds until the window has room again.

json

{
    "success": false,
    "error": {
        "type": "https://idparse.com/errors/rate-limited",
        "code": "rate_limited",
        "title": "Rate Limit Exceeded",
        "status": 429,
        "detail": "You have exceeded your plan's per-minute request limit."
    }
}

When all included scans are used, the API also returns 429, but with another code. Retry-After holds the seconds until the next calendar month begins.

json

{
    "success": false,
    "error": {
        "type": "https://idparse.com/errors/quota-exhausted",
        "code": "quota_exhausted",
        "title": "Monthly Quota Exhausted",
        "status": 429,
        "detail": "You have used all requests included in your plan for this month."
    }
}

Both answers are free of charge. Read error.code to tell them apart.

Tips:

Send a good image the first time. An unreadable document is free of charge, but it still counts toward the per minute limit.
Store the result of a success on your side. Do not send the same file again, because every success is charged.
Spread large batches over time instead of sending all files at once.
Monitor your usage with the Quota endpoint or the Dashboard.
Upgrade your plan for more included scans at Pricing.

Quota Endpoint

GET /v1/quota returns your plan, your included scans and your usage. It is free of charge, it never counts as a scan, and it stays reachable after your included scans are used up. It still counts toward the per minute limit.

bash

curl -s "https://api.idparse.com/v1/quota" \
  -H "Authorization: Bearer YOUR_API_KEY"

The full response is described in Endpoints.