Обробка помилок
Невдалі відповіді API викидають RequiplyError:
import { RequiplyError } from '@requiply/api-sdk';
try {
await requiply.sales.create({ lines: [{ saleItemId, quantity: 1 }], paymentMethod: 'liqpay' });
} catch (error) {
if (error instanceof RequiplyError && error.reason === 'client_email_required') {
console.error('LiqPay needs a client with an email');
} else {
throw error;
}
}
Властивості помилки
| Властивість | Що містить |
|---|---|
status | HTTP-статус відповіді, наприклад 400, 403, 404, 409 або 429. |
message | Зрозуміле людині повідомлення API, а якщо його немає, текст HTTP-статусу. Показуйте його людям, але не будуйте логіку на його тексті. |
reason | Машиночитна причина, коли API її надає, наприклад feature_disabled. Будуйте логіку саме на ній. |
data | Додаткові поля, які API надіслав разом із помилкою, зокрема reason. |
details | Розібране тіло відповіді або сирий текст відповіді, якщо це не JSON. |
retryAfter | Скільки секунд чекати, із заголовка Retry-After відповіді 429. |
Причини помилок
reason заповнюють запити на бронювання з публічними ключами, ендпоінти Продажі і рядки продажу в розрахунках ціни та бронюваннях:
reason | Статус | Значення |
|---|---|---|
request_only | 403 | Публічний ключ викликав bookings.create() без asRequest: true. |
feature_disabled | 403 | Увімкнути продажі вимкнено, або організація не на тарифі Advanced. |
selling_disabled | 403 | Публічний ключ запросив товари на продаж, коли організація не продає клієнтам. |
out_of_stock | 409 | Публічний ключ запросив більше одиниць, ніж є на полиці. data.saleItemId називає товар, data.availableQuantity показує, скільки залишилося. |
invalid_lines | 400 | Рядок не має товару або має кількість, яка не є цілим числом, більшим за нуль. |
duplicate_line | 400 | Той самий товар є у двох рядках. |
sale_item_not_found | 404 | Товару не існує в цій організації. |
sale_item_archived | 409 | Товар архівовано, тож його не можна продати. |
invalid_payment | 400 | paymentMethod не є відомим способом оплати. |
payment_method_unavailable | 400 | Організація не має активної інтеграції для цього способу оплати. |
client_email_required | 400 | LiqPay надсилає рахунок електронною поштою, тому продаж потребує клієнта з email. |
sale_not_found | 404 | Продажу не існує. |
Можуть зʼявлятися нові причини, тож завжди залишайте запасну гілку. Більшість інших помилок, як-от відсутнє поле чи невідоме бронювання, містять лише status і message.
Обмеження частоти запитів
Кожен ключ може робити 100 запитів на хвилину. Наступні запити викидають RequiplyError зі status 429 і retryAfter у секундах. У браузерах retryAfter відсутній, бо API не відкриває цей заголовок для міждоменних запитів. Зачекайте кілька секунд перед повторною спробою.
Відхилені бронювання не є помилками
bookings.create() не викидає помилку, коли організація не може прийняти бронювання, наприклад тому що товари на ці дати зайняті або видача припадає на неробочий час. Метод повертає success: false разом із message, а іноді й reason. Див. Бронювання.
Помилки, які не є RequiplyError
Перевірка конструктора та відсутні API середовища викидають TypeError: відсутній чи порожній apiKey, недоступний fetch або секретний ключ у браузері. Мережеві збої та перервані запити завершуються помилкою, яку викидає ваша реалізація fetch.