Skip to content

Коды ошибок IZI API

Опубликовано: · Обновлено: (28 дней назад)· IZI Team

Ошибки в 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Код
Синтаксис, несуществующее поле, неверный тип400GRAPHQL_PARSE_FAILED, GRAPHQL_VALIDATION_FAILED, BAD_USER_INPUT
Массив операций в теле (батчинг выключен)400BAD_REQUEST
Тело больше 256 КБ413PAYLOAD_TOO_LARGE
Сложность запроса больше 750500QUERY_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);
}
}
}

Частые вопросы

Почему IZI API возвращает HTTP 200 даже при ошибке?

Это стандартное поведение GraphQL. HTTP-статус 200 означает что запрос был принят и обработан. Бизнес-ошибки возвращаются в поле errors внутри тела ответа. Обрабатывайте оба случая.

Чем отличается Forbidden от Unauthorized?

Unauthorized — токен не передан, истёк или недействителен, а поле требует авторизации. Forbidden — токен действителен, но у роли или у пользователя нет прав на операцию.

Где взять полный список кодов?

Коды — значения перечисления ErrorCodes в схеме GraphQL, их около 350. Introspection на контурах выключена, поэтому актуальную схему (SDL) запрашивайте у IZI.

О продукте IZI