Ошибки и коды состояния
При разработке вызов работает. Теперь вы пишете ту часть, которая пригодится в продакшене, — блок catch. Сама по себе ошибка HTTP от стороннего API мало что объясняет: красный код состояния и никакого ясного ответа на единственный важный в три часа ночи вопрос — дело в моём запросе, ключе, плане или в их серверах? И когда повторять запрос, а когда — показывать ошибку пользователю?
В Lingo.dev ответ заложен в структуру ошибок. Все ошибки эндпоинтов на этих страницах, синхронных и асинхронных, возвращаются в виде одинакового объекта JSON с кодом состояния из одной фиксированной таблицы. API платформы по пути /v2 использует другой, стандартный формат описания ошибок. См. Ошибки API платформы. Код состояния — не просто метка, а инструкция: он подсказывает, нужно ли исправить запрос, заменить ключ, пополнить счёт, сделать паузу или повторить запрос. Посмотрите на код — и поймёте, что делать дальше. Один обработчик с логикой по коду состояния охватывает весь API.
На этой странице:
- Формат ошибки
- Коды состояния
- При каких ошибках повторять запрос
- 402 и 429: два разных лимита
- Где искать ошибки асинхронных заданий
- Ошибки API платформы
Формат ошибки#
У всех ответов с кодом вне диапазона 2xx одинаковое тело: объект JSON с единственным полем message, которое описывает, что пошло не так.
{
"message": "Invalid API key"
}Это весь контракт. Не нужно разбирать внешнюю оболочку или отдельно обрабатывать формат ошибок каждого эндпоинта. Ответ 400 от /process/localize и ответ 404 при поиске задания имеют одинаковую структуру — отличаются только код состояния и текст message.
Ориентируйтесь на код состояния, а не на текст сообщения
Код состояния HTTP — стабильный ориентир. Стройте логику обработки ошибок на нём. Строка message предназначена для человека, который читает логи. Это описание, а не машиночитаемый код ошибки, поэтому не привязывайте обработку к точным формулировкам.
Коды состояния#
Семь кодов состояния охватывают все ответы. Здесь они сгруппированы по тому, кто устраняет проблему. Эта же группировка определяет, когда повторять запрос.
В запросе есть проблема (исправьте запрос, не повторяйте его вслепую):
| Код | Значение |
|---|---|
400 Bad Request | Запрос не прошёл проверку: отсутствует поле, указана неверная локаль, callbackUrl использует HTTP вместо HTTPS или тело запроса имеет неверный формат. |
401 Unauthorized | Заголовок X-API-Key отсутствует или недействителен. См. Аутентификация. |
403 Forbidden | Ключ действителен, но не даёт доступа к запрошенному ресурсу. |
404 Not Found | Ресурс — движок, задание или группа заданий — не существует. |
Организация достигла лимита учётной записи (решите проблему в настройках оплаты):
| Код | Значение |
|---|---|
402 Payment Required | Организация достигла кредитного лимита. |
429 Too Many Requests | Организация исчерпала суточную квоту токенов. Перейдите на более высокий план, чтобы увеличить лимит. |
Сбой на нашей стороне (временный — повторите запрос):
| Код | Значение |
|---|---|
500 Internal Server Error | Непредвиденный сбой: ошибка базы данных или сбой вызова перевода во всех моделях, настроенных в движке. |
401 и 403 похожи, но означают разные проблемы: 401 — нам вообще не удалось определить, кто отправил запрос, а 403 — ключ распознан, но доступ для него закрыт. При 401 нужно разобраться с самим ключом (заменить или проверить его), а при 403 — с правами доступа ключа.
При каких ошибках повторять запрос#
Первый вопрос разработчика, который не принимает таблицу ошибок на веру, обычно остаётся без ответа: при каких из них повторять запрос? Группировка выше как раз на него отвечает.
- 4xx — не повторяйте запрос вслепую.
400,401,403или404указывают на проблему в вашем запросе. Тот же запрос приведёт к той же ошибке. Исправьте входные данные, ключ или ИД ресурса, затем отправьте запрос ещё раз. - 402 и 429 — сделайте паузу и разберитесь с лимитом. Это не временные сбои на уровне запроса: следующие запросы будут упираться в то же ограничение, пока ситуация с лимитом не изменится. Прекратите непрерывные повторы, сообщите о лимите и решите проблему: пополните счёт или перейдите на более высокий план.
- 500 — повторите запрос с задержкой. Это единственный класс действительно временных сбоев.
500может означать, что при этом вызове время ожидания истекло у всех настроенных моделей. Повторный запрос может попасть на работающую модель. Увеличивайте задержку экспоненциально и ограничивайте число попыток.
Асинхронный API сообщает результаты иначе
Эти правила повторных попыток относятся к синхронным вызовам, которые вы выполняете сами. Асинхронный API локализации не передаёт результат работы через код состояния: POST возвращает 202, как только запрос принят, а каждая целевая локаль обрабатывается как отдельное задание в устойчивых к сбоям фоновых рабочих процессах. Вместо того чтобы перехватывать код состояния исходного вызова, вы опрашиваете задание или получаете результат через вебхук. См. где искать ошибки асинхронных заданий.
402 и 429: два разных лимита#
Эти два кода уровня учётной записи выглядят похоже — оба словно говорят «у вас всё закончилось». Если их перепутать, можно начать решать не ту проблему. Это разные лимиты, и решения у них тоже разные:
402 Payment Required— организация достигла кредитного лимита. Это ограничение связано с оплатой. Следующие вызовы будут завершаться ошибкой, пока не изменится состояние расчётов организации.429 Too Many Requests— организация исчерпала суточную квоту токенов. Это лимит использования, который периодически сбрасывается. Его можно увеличить, перейдя на более высокий план.
Вот почему их важно различать в обработчике: 402 требует действий человека для решения вопроса с оплатой, а при 429 можно дождаться сброса квоты или увеличить её, перейдя на более высокий план. Общее сообщение «проблема с оплатой» в обоих случаях скрывает, что именно нужно сделать ответственному за систему.
Тело ответа 402 выглядит так же, как у любой другой ошибки. Именно код состояния указывает на кредитный лимит:
{
"message": "Organization has reached its credit limit"
}Где искать ошибки асинхронных заданий#
Здесь важно провести границу: за ней обработчик кодов состояния уже не подходит.
Коды состояния на этой странице относятся к транспортному уровню: они показывают, принял ли API ваш HTTP-запрос и смог ли его обслужить. 202 от Асинхронного API означает, что запрос принят, а не что перевод выполнен успешно. Асинхронное задание может быть принято без ошибок, но завершиться сбоем позже, если во время работы истечёт время ожидания модели. Такой сбой не отражается в коде состояния HTTP исходного вызова — он записывается в самом задании.
Поэтому ошибки асинхронной обработки отражаются в трёх местах, и ни одно из них не входит в эту таблицу:
- Статус задания. При сбое обработки локали в задании указываются
status: "failed"иerrorMessage. См. статусы заданий. - Статус группы. Если часть локалей обработана успешно, а часть — с ошибкой, группа получает статус
partial. Результаты успешно обработанных локалей всё равно отправляются. См. как отслеживать группу заданий. - Доставка вебхука. Сбой передаётся как событие
translation.failedс полемerror. См. доставка вебхуков.
Есть ещё один момент, который часто вызывает путаницу: сбой некритичного этапа пайплайна не приводит к сбою задания. Задание завершается со статусом completed_with_warnings и предупреждениями по отдельным шагам, а не с ошибкой. Это вопрос наблюдения за пайплайном, а не кода ошибки. См. как наблюдать за запусками пайплайна.
Ошибки API платформы#
API платформы по пути https://api.lingo.dev/v2 возвращает ошибки иначе: в формате описания ошибок по стандарту RFC 9457, с типом содержимого application/problem+json:
{
"type": "https://lingo.dev/docs/api/errors/glossary-in-use",
"status": 409,
"title": "Glossary in use",
"detail": "Glossary gls_1 cannot be deleted while 2 engines apply it. Detach it from those engines first.",
"id": "gls_1",
"engineCount": 2
}typeопределяет проблему. Это ссылка на отдельную страницу этой проблемы, где перечислены её поля и эндпоинты, которые её возвращают. Стройте логику обработки наtype.statusповторяет код состояния HTTP.title— краткое описание, одинаковое для всех ошибок одного типа.detailсообщает, что произошло в этот раз и что делать дальше. Этот текст предназначен для человека: показывайте его, а не разбирайте программно.- Другие поля содержат данные о конкретном случае, например
idиengineCountвыше.detailформируется только на их основе, поэтому клиент может составить собственный текст на своём языке, используяtypeи эти поля.
Если запрос не проходит проверку, в ответе возвращается 400, а в errors перечисляются все недопустимые значения в виде пар { "path", "message" }. Каждый эндпоинт также может вернуть service-unavailable (503), при котором можно безопасно повторить запрос с задержкой, и internal-server-error (500).
Каждый код состояния соответствует одному правилу:
| Код | Значение |
|---|---|
401 | Не удалось определить, кто отправил запрос. |
402 | Ограничение плана или права доступа, которое снимается переходом на более высокий план или пополнением счёта. |
403 | Отправитель запроса определён, но это действие для него запрещено. |
404 | Ресурс не существует или отправитель запроса не может его видеть. |
409 | Запрос конфликтует с текущим состоянием: например, ресурс всё ещё используется. |
422 | Формат запроса верен, но правило запрещает его выполнение. |
429 | Лимит, который сбрасывается со временем. |
502 | Сбой у внешнего провайдера. |
503 | Временный сбой на нашей стороне. Повторите запрос с задержкой. |
Что дальше#
Чтобы написать надёжный обработчик ошибок, начните с двух вопросов, которые возникнут уже в начале интеграции: как работает аутентификация и где искать результаты асинхронной обработки.