Ошибки и коды состояния
Как читать ответы API об ошибках, повторять неудачные запросы и отличать ошибки HTTP от сбоев перевода.
Проверьте статус HTTP, прежде чем декодировать успешный ответ. API по адресу https://api.lingo.dev/v2 возвращает подробности ошибок в формате JSON. Успешно полученное задание может описывать работу, завершившуюся с ошибкой, поэтому проверьте и статус задания.
Как читать ответ об ошибке #
Ответы об ошибках используют Content-Type: application/problem+json. Основные поля — type, title, status и detail. Именованные ошибки также содержат поля, указывающие на затронутый ресурс или способ исправления.
В этом примере задание локализации не найдено:
{
"type": "https://lingo.dev/docs/api/errors/localization-job-not-found",
"title": "Localization job not found",
"status": 404,
"detail": "Localization job lfr_example not found.",
"id": "lfr_example"
}URI в type определяет ошибку. Поля и эндпоинты для каждой именованной ошибки описаны в каталоге ошибок API. При сохранении или классификации ошибки оставляйте возвращённый URI без изменений.
Как исправить некорректный запрос #
Если запрос не проходит проверку, API возвращает 400 Bad Request с type: "about:blank". Если доступны подробности проверки, в errors перечислены path и message для каждой проблемы:
{
"type": "about:blank",
"title": "Bad Request",
"status": 400,
"detail": "Request validation failed",
"errors": [
{
"path": ["payload", "documents", 0, "source"],
"message": "Expected a JSON object"
}
]
}Путь начинается с проверяемой части запроса, например payload. Затем идут имена свойств и индексы массивов с отсчётом от нуля. В этом примере путь указывает на source в первом элементе documents в теле запроса. Перед повторной отправкой исправьте указанное значение в соответствии со схемой эндпоинта. about:blank — общий тип ошибки, поэтому в каталоге именованных ошибок для него нет записи.
Как выбрать способ восстановления #
| Статус HTTP | Типичная причина | Что делать дальше |
|---|---|---|
| 400 | Запрос не соответствует схеме маршрута. | Исправьте путь, параметры запроса, заголовки или тело по полученным подробностям проверки. |
| 401 | Учётные данные отсутствуют, недействительны или срок их действия истёк. | Загрузите нужный ключ или обновите сеанс пользователя. |
| 402 | Недостаточно кредитов, недоступны возможности плана или сервисный ключ отключён после сокращения прав RBAC. | Прочитайте описание ошибки и выполните указанные требования к учётной записи или плану. |
| 403 | Не хватает разрешения, требуется идентификация пользователя или действует ограничение флага функции. | Проверьте, кто отправляет запрос и какие права доступа нужны для операции. |
| 404 | Ресурс не существует или не виден отправителю запроса. | Проверьте идентификатор, организацию и права доступа к ресурсу. |
| 409 | Операция конфликтует с состоянием ресурса. | Получите текущее состояние ресурса. Следуя указаниям, загрузите недостающие артефакты, завершите выполняемую работу или обновите закрытую проверку. |
| 413 | Загружаемые данные или тело запроса превышают допустимый размер. | Уменьшите объём входных данных или разделите работу на части. Размер каждого загружаемого артефакта — не более 25 МиБ. |
| 422 | Структура запроса верна, но он нарушает ограничения операции. | Устраните указанную проблему, например недопустимую правку при проверке или повторное использование ключа идемпотентности. |
| 429 | Достигнут лимит использования или операций. | Если в ответе об ошибке указано время повторной попытки, соблюдайте его. Если нет, проверьте лимит учётной записи, прежде чем повторять запрос. |
| 5xx | Серверу или зависимому сервису не удалось выполнить запрос. | Сохраните ИД ресурса и запроса. Повторяйте запрос только с учётом семантики операции. |
detail объясняет конкретный сбой. Одного статуса недостаточно для полной классификации. Ответы прокси-сервера или ответы при сетевом сбое могут не содержать тела с описанием ошибки. Сохраните статус HTTP и читаемый текст ответа для диагностики, но не записывайте секреты в логи.
Как повторно отправить запрос на локализацию #
Перед отправкой запроса на создание сохраните его Idempotency-Key. Если ответ потеряется, повторите тот же запрос с тем же ключом, чтобы получить исходное задание. С новым ключом будет создано новое задание.
После создания сохраните ИД задания. Получите это задание, прежде чем решать, нужно ли создавать другое. Загружаемые данные должны побайтно соответствовать их адресу SHA-256. Перед запуском завершите все недостающие загрузки. Повторный вызов /start работает с тем же заданием.
Проверки допуска выполняются при запуске. При DailyTokenLimitReached или нехватке кредитов задание остаётся в ожидании: вы сможете запустить его позже, когда решите проблему с учётной записью. Создание новых заданий не помогает обойти лимит учётной записи.
Как отличить ошибку запроса от сбоя выполнения задания #
Статус HTTP 200 в ответе от GET /v2/localization/jobs/:id означает, что задание получено. При этом в status._tag всё ещё может быть Failed. Проверьте status.message, статус каждой цели, а также предупреждения и сбои на этапах.
Результаты завершённых целей остаются доступными для скачивания, даже если другая цель завершилась с ошибкой. Сохраните их, устраните причину сбоя и отправьте заново только ту работу, которую нужно выполнить повторно. Истечение времени ожидания при опросе со стороны клиента не отменяет задание.
У провижининга есть свои результаты по типам и способы восстановления. У решений по проверке — свои ошибки закрытой проверки и недопустимых правок. При восстановлении учитывайте состояние этих ресурсов, а не повторяйте исходный запрос на запись при любом сбое.