Ошибки и повторные запросы
HTTP-ошибки FreeAIOCR API, идемпотентность, безопасные повторы и действия при неопределённом списании.
Общие руководства относятся к API текста и таблиц. Входные данные, форматы и особые ошибки описаны в справочнике каждого API.
Ответы с ошибками
Пример ошибки JSON:
{
"request_id": "b2c8ec98-2a36-4f87-99d2-3d7839b92518",
"error": {
"code": "insufficient_balance",
"message": "Recognition did not complete",
"required_reservation_usd": "0.011288000"
}
}Коды состояния HTTP
| HTTP | error.code |
|---|---|
| 400 | invalid_request, invalid_idempotency_key, invalid_image |
| 401 | unauthorized |
| 402 | insufficient_balance |
| 403 | account_unavailable |
| 405 | invalid_request |
| 409 | idempotency_conflict, request_in_progress |
| 413 | image_too_large, input_limit_exceeded |
| 415 | unsupported_media_type |
| 422 | recognition_blocked |
| 429 | rate_limit_exceeded, concurrency_limit_exceeded |
| 502 | recognition_failed, output_truncated, empty_result, invalid_usage |
| 503 | service_unavailable, settlement_pending, export_failed |
| 504 | request_timeout |
| HTTP | Причина | Что делать |
|---|---|---|
| 400 / 413 / 415 | Неверный запрос, размер или формат | Исправьте файл или уменьшите его |
| 405 | Неправильный HTTP-метод | Используйте POST |
| 401 | API-ключ отсутствует или неверен | Проверьте Bearer-ключ |
| 403 | Аккаунт недоступен | Подтвердите аккаунт или устраните ограничение |
| 402 | Недостаточно доступного баланса | Пополните баланс; проверьте error.required_reservation_usd и правила резервирования |
| 409 | Конфликт ID или запрос выполняется | Для request_in_progress сохраните ID и изображение и повторите после ожидания; при конфликте исправьте ID операции |
| 429 | Ограничение частоты или параллелизма | Подождите согласно Retry-After |
| 422 / подтверждённый 502 | Подтверждённый сбой распознавания | Плата за распознавание не взимается; проверьте ошибку |
| 503 / 504 / неясный результат | Сервис, расчёт или тайм-аут не определены | Не считайте запрос неоплаченным; повторите с исходными Idempotency-Key и изображением |
Ошибки возвращаются в JSON с request_id, error.code и error.message. Во всех ответах используется Cache-Control: no-store. Распознавание не передаётся потоком: успешный ответ имеет выбранный формат, а ошибки остаются JSON. Сохраняйте X-Request-Id для поддержки.
Идемпотентность
Idempotency-Key — ID операции: 16–128 ASCII-букв, цифр или . _ : -. Для нового изображения нужен новый уникальный ID; для повтора сохраняйте ID, исходные байты и MIME. Область — аккаунт, даже при смене API-ключа. В течение 24 часов после принятия завершённая операция вернёт исходные request_id, результат и стоимость с Idempotency-Replayed: true, без новой генерации и списания.
Используйте отдельный Idempotency-Key для каждой новой операции или конечной точки. Общий идентификатор для текста и таблиц вызывает 409 idempotency_conflict. Для смены формата той же операции сохраняйте исходные ключ и изображение.
Стратегия повторов
При ошибке сети, request_in_progress или settlement_pending сохраните ID и изображение, подождите Retry-After секунд и повторите. Не создавайте новую операцию при неопределённом расчёте. Сохранённые окончательные ошибки повторяются; новый ID нужен только для намеренного запуска после подтверждённой ошибки. Через 24 часа ID может создать новую платную операцию; незавершённое восстановление всё ещё блокирует повторное использование.
Безопасность списаний
Подтверждённый сбой распознавания не оплачивается, но потерянный ответ или settlement_pending могут означать уже проведённое списание либо сохраняемый резерв. Пока результат неясен, не начинайте новую операцию с другим Idempotency-Key: повторяйте с тем же ID и изображением, а для поддержки сохраните X-Request-Id.