Коды ошибок IZI API
Коды ошибок IZI API
Заголовок раздела «Коды ошибок IZI API»Ошибки в GraphQL API возвращаются в поле errors тела ответа, а не через HTTP-статус. HTTP 200 при ошибке — норма. Это надо знать, чтобы не написать обработчик только на HTTP-уровне.
Структура ошибки
Заголовок раздела «Структура ошибки»{ "data": null, "errors": [ { "message": "User not authenticated", "path": ["userProfile"], "extensions": { "code": "Unauthorized", "message": "User not authenticated" } } ]}Поля в extensions:
code— машиночитаемый код ошибки (используйте его в switch/case)message— текст ошибки, тот же, что вmessageверхнего уровня
Отдельные ошибки добавляют в extensions свои поля с подробностями. Поля locations у бизнес-ошибок и у ошибок валидации нет: сервер разбирает документ с noLocation. У синтаксической ошибки locations есть — она указывает позицию в тексте самого запроса.
Исключения из правила «HTTP 200» — всё, что отклоняется до выполнения операции:
| Что произошло | HTTP | Код |
|---|---|---|
| Синтаксис, несуществующее поле, неверный тип | 400 | GRAPHQL_PARSE_FAILED, GRAPHQL_VALIDATION_FAILED, BAD_USER_INPUT |
| Массив операций в теле (батчинг выключен) | 400 | BAD_REQUEST |
| Тело больше 256 КБ | 413 | PAYLOAD_TOO_LARGE |
| Сложность запроса больше 750 | 500 | QUERY_TOO_COMPLEX |
Последняя строка — та, на которой ломается типовая обработка: запрос сложнее 750 отклонён навсегда, но приходит с кодом 500, то есть выглядит как сбой сервера. Повторять его бессмысленно — смотрите на extensions.code, а не на HTTP-статус.
Частые коды
Заголовок раздела «Частые коды»Коды — значения перечисления ErrorCodes. Базовые коды записаны в стиле PascalCase, коды отдельных модулей — часто в стиле UPPER_SNAKE_CASE. Сравнивайте код строкой целиком, без приведения регистра.
| Код | Когда |
|---|---|
Unauthorized | Токен не передан, истёк или недействителен, а поле требует авторизации |
Forbidden | Токен действителен, но роли или пользователю не хватает прав |
NotFound | Объект не найден |
InvalidInput | Входные данные не прошли проверку; так же отклоняется операция без имени |
InternalServerError | Внутренняя ошибка, которую API бросил сам — нарушен инвариант |
INTERNAL_SERVER_ERROR | Непредвиденная ошибка сервера: этот код подставляет Apollo, и именно он приходит чаще |
TooManyAttempts | Слишком много неудачных попыток входа |
AccountDeleted | Аккаунт игрока удалён, его токен больше не действует |
INSUFFICIENT_BALANCE | Недостаточно средств |
DEVICE_OFFLINE | Устройство не в сети |
Остальные коды относятся к конкретным модулям — заказам, сессиям, складу, эквайрингу — и описаны в схеме рядом с операциями, которые их возвращают.
Обработка ошибок в коде
Заголовок раздела «Обработка ошибок в коде»graphql-request выбрасывает исключение, если в ответе есть errors. Код достаётся из extensions:
async function requestIZI(client, document, variables) { try { return await client.request(document, variables); } catch (error) { const code = error.response?.errors?.[0]?.extensions?.code;
switch (code) { case "Unauthorized": // Токен не передан или истёк: обновления токена нет, нужен новый вход throw new SessionExpiredError(error.message);
case "Forbidden": throw new PermissionError(error.message);
case "NotFound": throw new NotFoundError(error.message);
default: throw new IZIError(code, error.message); } }}Связанные страницы
Заголовок раздела «Связанные страницы»- Авторизация и токены — ошибки входа подробнее
- Примеры SDK — готовые обёртки на JS и Python
См. также
Заголовок раздела «См. также»Частые вопросы
Почему IZI API возвращает HTTP 200 даже при ошибке?
Это стандартное поведение GraphQL. HTTP-статус 200 означает что запрос был принят и обработан. Бизнес-ошибки возвращаются в поле errors внутри тела ответа. Обрабатывайте оба случая.
Чем отличается Forbidden от Unauthorized?
Unauthorized — токен не передан, истёк или недействителен, а поле требует авторизации. Forbidden — токен действителен, но у роли или у пользователя нет прав на операцию.
Где взять полный список кодов?
Коды — значения перечисления ErrorCodes в схеме GraphQL, их около 350. Introspection на контурах выключена, поэтому актуальную схему (SDL) запрашивайте у IZI.
ООО «ИЗИ», ИНН 7842227686, ОГРН 1257800012249, 191024, г. Санкт-Петербург, Перекупной пер., д. 15-17, литера А, помещ. 3-н, офис 1, admin@izi.is · Настройки cookie