Errors and retries
Avoid duplicate checks and handle temporary failures.
This page describes receipt checks at /v1/checks. Standalone PDF inspection has separate limits and retry rules.
Retry without creating a new check
Create an Idempotency-Key for each check attempt: a string of up to 128 characters.
If the response is lost, repeat the request with the same key, file, filename and parameters.
Within 24 hours, you receive the saved result without using another check from your allowance.
Use a new key for a different attempt or changed data. Reusing a key with different
content returns 409 idempotency_conflict.
HTTP errors
When a request is rejected, the API returns the appropriate HTTP status and a body
with this structure. The message below is an example; use code for automated handling.
{
"error": {
"code": "validation",
"message": "Некорректные expectation или tags",
"details": {}
}
}| HTTP | Code | Action |
|---|---|---|
| 401 | unauthorized | Check your API key |
| 403 | tenant_disabled, profile_forbidden | Contact support to check your access |
| 404 | not_found | Check the check ID and API key |
| 409 | processing | Wait for Retry-After and retry |
| 409 | idempotency_conflict | Use a new key for changed data |
| 413 | upload_too_large | Submit a file within the size limit |
| 422 | validation, unknown_profile, identifier_required | Correct the request parameters |
| 429 | rate_limit, quota_exceeded | Wait for Retry-After; contact support if needed |
| 503 | overloaded, database_unavailable | Retry later with the same idempotency key |
Retry-After is expressed in seconds. If it is absent, increase the delay between
retries rather than sending continuous requests.
HTTP 200, but processing failed
A response with status: failed indicates a processing error. Save the id and read
error. If error.retryable: true, you can start another attempt with a new
Idempotency-Key; the old key returns the saved failure. If retrying does not help,
send the check ID to support.
status: done with recommendation: reject is a completed check, not a technical
failure. Do not automatically resubmit the same document.
Size, time and limits
- The standard maximum file size is 15 MB.
- Processing takes up to 45 seconds plus file transfer time; allow extra time in your client timeout.
- The standard rate limit is 120 new checks per minute. Your company’s limits may differ.
- A completed check uses one unit of your allowance, regardless of the recommendation.
A processing error with
status: faileddoes not use the allowance. - Reading results or sending feedback does not create another check.
Your remaining allowance and its reset time are shown in the dashboard.