Помилки¶
Помилки використовують той самий конверт усюди, зі стабільним code, на який можна
розгалужувати логіку.
{
"success": false,
"error": {
"code": "validation_error",
"message": "name is required",
"details": { "field": "name" }
}
}
code— стабільний машинозчитуваний рядок (безпечно перемикатися на ньому).message— читабельний текст, формулювання може змінюватись з часом.details— опційний структурований контекст (проблемне поле, потрібний scope, …).
HTTP-статус відповідає помилці.
| HTTP | code |
Значення |
|---|---|---|
| 400 | bad_request |
некоректний запит |
| 401 | unauthorized |
відсутній або невірний API-ключ |
| 403 | forbidden |
ключу бракує потрібного scope (details.required) |
| 403 | limit_exceeded |
вичерпано ліміт тарифу; у message — який саме (напр. Limit: sales) |
| 404 | not_found |
ресурс не існує (або не ваш) |
| 405 | method_not_allowed |
цей HTTP-метод не підтримується на цьому шляху |
| 409 | conflict |
запит конфліктує з поточним станом (наприклад, продаж із таким external_id уже є — details.sale_id) |
| 422 | validation_error |
поле не пройшло валідацію (details.field) |
| 422 | carrier_error |
служба доставки відхилила запит (напр. ТТН); у message її текст |
| 422 | promotion_* |
акцію позиції продажу не застосовано, див. Продаж за акцією |
| 429 | rate_limited |
перевищено ліміт запитів — повторіть через Retry-After секунд |
| 500 | server_error |
неочікувана помилка на нашому боці |
| 502 | carrier_error |
служба доставки не відповіла (напр. пошук адреси) — повторіть пізніше |
Розгалужуйтесь на code, не на message
Вважайте message лише текстом для показу. Програмуйте на code та HTTP-статус.
Composite /query ізолює помилки по під-запитах — невдалий під-запит містить цей самий
об'єкт error у своєму слоті, тоді як інші повертають data. Див.
Composite-запит.