Коди помилок

Кожен 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 — формати відповідей і що стабільне