Коди помилок
Кожен 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
Ні код провайдера, ні жоден зареєстрований аліас не збіглися з надісланим значенням.
Робіть: перевірте актуальний перелік у GET /v1/providers, а аліаси кожного — у GET /v1/providers/{code}. Див. Providers and Vendors.
language_unsupported — 409
Провайдер і мова існують; пара зафіксована як неробоча.
409, а не 404, бо обидва названі ресурси реальні — відмовлено саме їхній комбінації, а викликач, що вічно ретраїть той самий 404, робив би хибний висновок.
Робіть: оберіть іншого провайдера для цієї мови. GET /v1/languages/{code}/providers показує, хто її візьме.
Info
/v1/resolve віддає це в тілі
Ендпоінт повертає 200 із supported: false і code: null, а не кидає помилку, тож викликач може залогувати пару й піти далі без обробки винятків. Форма 409 з'являється там, де непідтримувана пара — це жорсткий збій.
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 — формати відповідей і що стабільне