> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Помилки User API

> Коди стану та коди помилок, які повертає User API.

Помилки повертають `success: false`, стабільний `code`, зрозумілий `error` і `request_id`.

```json theme={"system"}
{
  "success": false,
  "code": "INSUFFICIENT_SCOPE",
  "error": "This API key needs the orders:write permission",
  "required_scope": "orders:write",
  "request_id": "req_7YbK2mQ9xP1cRt4v"
}
```

Повторюйте лише відповіді `429` (після `Retry-After`) і `5xx`, з тим самим `Idempotency-Key`.

## Автентифікація та ліміти

| Код | Статус | Як виправити |
| :- | :- | :- |
| `MISSING_API_KEY` | `401` | Надішліть `x-api-key`. |
| `MISSING_STORE_HASH` | `401` | Надішліть `x-store-hash`. |
| `INVALID_API_KEY` | `401` | Ключ неправильний або відкликаний. |
| `API_KEY_EXPIRED` | `401` | Створіть новий ключ або подовжте термін дії поточного. |
| `IP_NOT_ALLOWED` | `403` | Надсилайте запит із дозволеної IP-адреси або змініть налаштування ключа. |
| `STORE_NOT_ALLOWED` | `403` | Ключ належить іншому обліковому запису або обмежений іншими магазинами. |
| `STORE_NOT_FOUND` | `404` | Перевірте `x-store-hash`. |
| `INSUFFICIENT_SCOPE` | `403` | Надайте ключу дозвіл, вказаний у `required_scope`. |
| `STORE_API_NOT_IN_PLAN` | `403` | Ваш тариф не включає Store API. |
| `RATE_LIMITED` | `429` | Понад 300 запитів за хвилину. |
| `STORE_API_MONTHLY_QUOTA_EXCEEDED` | `429` | Місячну квоту вичерпано. Скидається 1-го числа (UTC). |

## Запити

| Код | Статус | Значення |
| :- | :- | :- |
| `INVALID_JSON` | `400` | Тіло запиту не є коректним JSON. |
| `PAYLOAD_TOO_LARGE` | `413` | Тіло запиту занадто велике. |
| `VALIDATION_FAILED` | `422` | Поле відсутнє або некоректне. Його назва вказана в `details.field`. |
| `NOT_FOUND` | `404` | Такого запису в цьому магазині немає. |
| `IDEMPOTENCY_KEY_REUSED` | `422` | `Idempotency-Key` уже використано з іншим тілом. |
| `IDEMPOTENCY_IN_PROGRESS` | `409` | Перший запит із цим ключем ще виконується. |
| `ENDPOINT_RETIRED` | `410` | Ендпоінт видалено. У повідомленні вказано заміну. |
| `FEATURE_NOT_ENABLED` | `403` | Магазин не схвалено для цієї функції (фізичні товари, партнерська програма). |
| `INTERNAL_ERROR` | `500` | Помилка на нашому боці. Повторіть спробу, потім зверніться до підтримки з `request_id`. |

## Коди ресурсів

| Код | Статус | Значення |
| :- | :- | :- |
| `PRODUCT_NOT_FOUND` | `404` | Позиція замовлення посилається на товар поза вашим магазином. |
| `OUT_OF_STOCK` | `409` | Недостатньо залишків для замовлення. |
| `TOTAL_MISMATCH` | `409` | `expected_total_cents` відрізняється від фактичної ціни. |
| `INVOICE_PAID` | `409` | Оплачені замовлення не можна скасувати. Натомість поверніть кошти. |
| `PAYMENT_IN_PROGRESS` | `409` | Платіж обробляється. |
| `INVOICE_CLOSED` | `409` | Скасовані або прострочені замовлення не можна завершити. |
| `INVOICE_NOT_PAID` | `409` | Повернути кошти або доставити можна лише оплачені замовлення. |
| `ALREADY_REFUNDED` / `REFUND_TOO_LARGE` | `409` | Сума для повернення відсутня або менша за запитану. |
| `DELIVERY_FAILED` | `502` | Оплачено, але доставка не вдалася. Викличте `/complete` ще раз. |
| `SLUG_TAKEN`, `SKU_TAKEN`, `COUPON_CODE_TAKEN` | `409` | Це значення вже використовується у вашому магазині. |
| `PLAN_LIMIT_REACHED` | `403` | Досягнуто ліміту товарів вашого тарифу. |
| `NOT_PAID`, `OVER_SHIPPED`, `CLOSED` | `409` | Неможливо створити відправлення для цього замовлення або цієї кількості. |
| `INVALID_TRANSITION` | `409` | Повернення або звернення не може перейти в цей статус. |
| `ENDPOINT_LIMIT_REACHED` | `409` | Не більше 16 ендпоінтів вебхуків на магазин. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.