Доступ
Ошибки
Все коды, которые может вернуть платформа, с дословными текстами ответов — по ним удобно искать в своих логах.
Как выглядит ошибка
Тело ошибки — объект с полем error. Тексты на русском, часть из них показывается сотрудникам в интерфейсе, поэтому они написаны человеческим языком, а не кодами. Иногда добавляется поле code с машинным идентификатором.
типичная ошибка
HTTP/1.1 403 Forbidden
Content-Type: application/json
{"error":"Forbidden: Missing permission manage_orders"}Что означают коды
- 400 — в запросе чего-то не хватает или значение неверное. Повторять бессмысленно, пока не исправите запрос.
- 401 — платформа не поняла, кто вы. Проблема в ключе.
- 403 — поняла, но не разрешает: не хватает права либо вы просите чужой бренд.
- 404 — записи нет. Либо она есть, но не ваша: платформа сознательно не различает эти случаи.
- 409 — состояние не позволяет выполнить действие. Например, заказ уже отгружен.
- 422 — данные поняли, но сопоставить не смогли: например, артикул не найден в каталоге.
- 429 — слишком часто. Ждите окно.
- 500 и 502 — сбой на стороне платформы. Повтор уместен.
Ошибки доступа
Подробный разбор с примерами — в разделе про ключи.
Ошибки
| Код | Ответ сервера | Когда возникает | Что делать |
|---|---|---|---|
| 401 | {"error":"Unauthorized"} | Ключ отсутствует, неизвестен, отозван, просрочен — или автор ключа потерял права. | Начните с проверки учётной записи автора ключа: это самая частая причина. |
| 401 | {"error":"Invalid token"} | Передан токен сессии с неверной подписью. | — |
| 401 | {"error":"Session expired"} | Сессия сотрудника истекла. Для интеграций по ключу не встречается. | — |
| 401 | {"error":"Missing Authorization: Bearer <apiKey>"} | Запрос к производственному API без заголовка. | — |
| 401 | {"error":"Invalid or inactive API key"} | Ключ площадки неизвестен или площадка выключена. | После отзыва старый ключ может работать ещё до 30 секунд. |
| 403 | {"error":"Forbidden: Missing permission <ключ>"} | У ключа нет конкретного права. | Перевыпустите ключ с этим правом. |
| 403 | {"error":"Forbidden: Missing required permission"} | Эндпоинт принимает несколько прав, но нет ни одного. | — |
| 403 | {"error":"Forbidden: brand not allowed"} | Запрошена запись чужого бренда по идентификатору. | Попытка попадает в журнал безопасности — не используйте это как способ проверки существования записи. |
| 403 | {"error":"Forbidden: no brand access configured"} | У ключа нет ни одного бренда. | — |
| 403 | {"error":"Позиция не принадлежит этой производственной площадке"} | Приёмка товара, который не относится к площадке ключа. | — |
Ошибки
| Код | Ответ сервера | Когда возникает | Что делать |
|---|---|---|---|
| 400 | {"error":"Bad request: at least one brand required"} | Создаётся запись, которая обязана принадлежать бренду, но бренд не указан. | Передайте бренд явно. |
| 400 | {"error":"Некорректный идентификатор товара"} | В пути передано не число. | Проверьте, что подставляете идентификатор, а не артикул. |
| 404 | {"error":"Заказ не найден"} | Заказа нет — либо он есть, но принадлежит другому бренду. | Платформа намеренно не различает эти случаи, чтобы не подтверждать существование чужих записей. |
| 500 | {"error":"Internal error"} | Непредвиденный сбой на стороне платформы. | Повторите позже. Если повторяется — сообщите время запроса и путь: по ним ошибку найдут в журнале. |
| 502 | {"error":"Bad Gateway"} | Служба временно недоступна, например во время выкатки. | Повторите через несколько секунд. |
Частота обращений
Ограничения стоят на публичных действиях — вход, восстановление пароля, отклики. На запросы по ключу к заказам, складу и товарам ограничений нет, но это не повод опрашивать платформу в цикле без паузы. Подробности в разделе про ограничения.
Ошибки
| Код | Ответ сервера | Когда возникает | Что делать |
|---|---|---|---|
| 429 | {"error":"Слишком много попыток. Попробуйте через 15 минут."} | Превышен лимит на действиях со входом и восстановлением пароля. | Дождитесь окна — время указано в заголовках RateLimit. |
| 429 | {"error":"Слишком много запросов. Попробуйте позже."} | Превышен лимит на публичных счётчиках переходов. | — |
| 503 | {"error":"Сервис временно недоступен. Попробуйте позже."} | Недоступно хранилище счётчиков попыток при проверке кодов подтверждения. | Платформа намеренно отказывает, а не пропускает: иначе ограничение можно было бы обойти. |
Как повторять запросы
Повторяйте только 429, 500, 502 и сетевые обрывы. Ошибки 400, 401, 403, 404 и 422 от повтора не пройдут.
повтор с нарастающей паузой
async function сЗапросом<T>(вызов: () => Promise<Response>): Promise<T> {
const повторяемые = new Set([429, 500, 502, 503, 504]);
let задержка = 500;
for (let попытка = 1; попытка <= 4; попытка += 1) {
const ответ = await вызов();
if (ответ.ok) return ответ.json() as Promise<T>;
if (!повторяемые.has(ответ.status) || попытка === 4) {
throw new Error(`Amarix ${ответ.status}: ${await ответ.text()}`);
}
await new Promise((r) => setTimeout(r, задержка));
задержка *= 2;
}
throw new Error("недостижимо");
}