Ошибки
Все ошибки приходят с типом application/problem+json (RFC 7807) и одинаковой формой — разбирать их можно одной функцией.
{
"type": "https://rkdash.com/docs/api/errors#insufficient_scope",
"title": "Недостаточно прав у ключа",
"status": 403,
"detail": "У ключа нет области доступа «write:prices». Добавьте её при создании ключа.",
"instance": "/api/v1/dishes/dish_.../price",
"code": "insufficient_scope",
"requestId": "b1f2...",
"errors": [{ "pointer": "filter[fudcost_gt]", "detail": "Ожидается число." }]
}| Код | Статус | Когда возникает | Что делать |
|---|---|---|---|
| unauthorized | 401 | Ключ не передан, не похож на ключ RKDash или не найден в базе. | Передайте заголовок Authorization: Bearer rk_live_… или X-Api-Key. |
| key_revoked | 401 | Ключ отозван в разделе «Настройки → API». | Выпустите новый ключ: отозванный не восстанавливается. |
| insufficient_scope | 403 | У ключа нет области доступа, которая нужна методу. | Добавьте область (например write:prices) в настройках ключа. |
| not_found | 404 | Объект не найден: чужой id, объект удалён или его нет в витрине. | Возьмите идентификатор из соответствующего списка — он непрозрачный и не угадывается. |
| validation_failed | 422 | Тело запроса или фильтры не прошли проверку схемы. | Смотрите массив errors: там поле (pointer) и причина. |
| invalid_request | 400 | Тело не JSON, пустое или отсутствует там, где нужно. | Проверьте Content-Type: application/json и корректность JSON. |
| invalid_cursor | 400 | Курсор пагинации повреждён. | Используйте значение meta.nextCursor как есть, не собирайте вручную. |
| conflict | 409 | Объект с такими данными уже есть (например, подписка на тот же адрес). | Найдите существующий объект и измените его через PATCH. |
| idempotency_conflict | 409 | Тот же Idempotency-Key отправлен с другим телом запроса. | Для нового тела нужен новый ключ идемпотентности. |
| rate_limited | 429 | Больше 100 запросов в минуту или всплеск больше 20 в секунду. | Подождите Retry-After секунд; заголовки X-RateLimit-* показывают остаток. |
| payload_too_large | 413 | Тело запроса больше 1 МБ. | Разбейте запрос: массовые движения склада отправляйте частями. |
| unsupported_version | 400 | Заголовок X-Api-Version содержит неизвестную дата-версию. | Проверьте список поддерживаемых версий в заголовке ответа и в changelog. |
| upstream_unavailable | 502 | Внешний источник не ответил: агент Mastra, платформа интеграций. | Повторите позже; в detail указано, кто именно не ответил. |
| internal_error | 500 | Внутренняя ошибка сервиса. | Сообщите requestId из ответа — по нему находится запись в журнале API. |