> ## 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.