Коды ошибок

Каждый error.code, когда он случается и что с ним делать.

Ветвитесь по error.code. Он стабилен. message для людей и может быть переформулирован.

{ "error": { "code": "language_not_found",
             "message": "Unknown language code: 'xx-YY'",
             "details": { "language": "xx-YY" } } }

Публичный API

language_not_found — 404

Код не совпал ни с каноническим кодом, ни с алиасом, и укорачивание тоже ничего не нашло.

Делайте: залогируйте сырое значение. Это либо опечатка на стороне отправителя, либо здесь нужен алиас — см. Добавить язык. Если вы классифицируете, а не резолвите, берите /v1/normalize: он отдаёт known: false с 200.

Не делайте ретраев. Ответ не изменится, пока кто-то не отредактирует каталог.

details.language несёт присланное вами значение.

provider_not_found — 404

Ни код провайдера, ни короткое имя, ни легаси service_name не совпали.

Делайте: проверьте актуальный перечень в GET /v1/providers. Легаси-имена консоли зарегистрированы как алиасы, так что если service_name из animated-spoon не сработал — провайдера здесь действительно нет; см. Providers and Vendors.

language_unsupported — 409

Провайдер и язык существуют; пара зафиксирована как нерабочая.

409, а не 404, потому что оба названных ресурса реальны — отказано именно их комбинации, а вызывающий, вечно ретраящий тот же 404, делал бы неверный вывод.

Делайте: выберите другого провайдера для этого языка. GET /v1/languages/{code}/providers показывает, кто его возьмёт.

validation_error — 422

Некорректный запрос: неправильный тип, отсутствующий параметр или батч свыше 500 пар.

details.fields перечисляет каждую проблему с её расположением.

payload_too_large — 413

Тело свыше 256 КБ. Разбейте батч.

internal_error — 500

Необработанное исключение. Сообщение намеренно обобщённое: неожиданное исключение может нести DSN или строку данных, так что оно идёт в лог, а не к вам.

Делайте: один ретрай с бэкоффом, затем сообщите с X-Correlation-Id из заголовков вашего ответа.

service_unavailable — 503

От /health/ready, когда база недоступна или каталог пуст (миграции прошли, сид — нет).

Только админка

Далее

• Errors and Conventions — форматы ответов и что стабильно