Ошибки и коды состояния

Как читать ответы API об ошибках, повторять неудачные запросы и отличать ошибки HTTP от сбоев перевода.

Проверьте статус HTTP, прежде чем декодировать успешный ответ. API по адресу https://api.lingo.dev/v2 возвращает подробности ошибок в формате JSON. Успешно полученное задание может описывать работу, завершившуюся с ошибкой, поэтому проверьте и статус задания.

Как читать ответ об ошибке #

Ответы об ошибках используют Content-Type: application/problem+json. Основные поля — type, title, status и detail. Именованные ошибки также содержат поля, указывающие на затронутый ресурс или способ исправления.

В этом примере задание локализации не найдено:

json
{
  "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 для каждой проблемы:

json
{
  "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, статус каждой цели, а также предупреждения и сбои на этапах.

Результаты завершённых целей остаются доступными для скачивания, даже если другая цель завершилась с ошибкой. Сохраните их, устраните причину сбоя и отправьте заново только ту работу, которую нужно выполнить повторно. Истечение времени ожидания при опросе со стороны клиента не отменяет задание.

У провижининга есть свои результаты по типам и способы восстановления. У решений по проверке — свои ошибки закрытой проверки и недопустимых правок. При восстановлении учитывайте состояние этих ресурсов, а не повторяйте исходный запрос на запись при любом сбое.