Помилки
Кожна помилка Shop API має один формат, і реагувати на неї треба за статусом і полем, а не за текстом.
Конверт
Section titled “Конверт”Кожна помилка — обʼєкт з одним полем message:
{ "message": "Unauthenticated."}422 додає errors — пласку карту, де ключ — шлях поля, а значення — список повідомлень:
{ "message": "Поле items.0.price має бути цілим числом.", "errors": { "locale": ["Поле locale є обовʼязковим."], "items.0.price": ["Поле items.0.price має бути цілим числом."] }}Для вкладених полів шлях буквальний і з крапками: items.0.price, items.3.interval_unit. Текст у message та errors йде мовою з Accept-Language (назви полів перекладаються також), тож логіку будуйте на статусі та ключі поля, ніколи — на тексті.
Статуси
Section titled “Статуси”| Статус | Коли | Що робити |
|---|---|---|
401 |
ключа немає, або він невідомий чи вже перегенерований | зупиніться й повідомте про це: інтеграція налаштована неправильно. Див. Автентифікацію |
429 |
з вашої адреси за хвилину було 60 невдалих спроб ключа | виправте ключ, зачекайте хвилину |
404 |
замовлення чи товар не цього магазину або його не існує | для замовлення — відкрийте нове; для товару — перевірте external_id |
409 |
замовлення вже не draft: оформлення почалося або його скасовано |
відкрийте нове замовлення й передайте віджету новий id. Див. Замовлення |
422 |
валідація | виправте тіло; errors називає поле |
Інших статусів для помилок клієнта Shop API не повертає. 5xx — збій на боці Neocarts: повторіть запит трохи згодом, а якщо він триває — напишіть на [email protected].
Повтор запиту на створення
Section titled “Повтор запиту на створення”Запит POST /v1/shop/orders/create не ідемпотентний: якщо ваш сервер повторить його після таймауту чи обриву звʼязку, Neocarts відкриє друге замовлення в статусі draft. Це нешкідливо — чернетка, яку ніхто не оплатив, нічого не списує і нічого не створює. Передайте віджету id того замовлення, відповідь на яке ви справді отримали, а інше просто забудьте.