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

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

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

Структура ошибки

{
  "data": null,
  "errors": [
    {
      "message": "Token is expired",
      "extensions": {
        "code": "TOKEN_EXPIRED",
        "timestamp": "2026-05-30T14:32:00Z"
      },
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["me"]
    }
  ]
}

Поля в extensions:

• code — машиночитаемый код ошибки (используйте его в switch/case)
• timestamp — время ошибки на сервере
• field — поле, вызвавшее ошибку (если применимо)
• details — дополнительный контекст (не всегда присутствует)

Коды авторизации

Код	HTTP	Описание	Действие
UNAUTHENTICATED	401	Токен отсутствует или не передан	Добавьте заголовок Authorization: Bearer <token>
TOKEN_EXPIRED	401	accessToken истёк	Обновите через refreshToken mutation
REFRESH_TOKEN_EXPIRED	401	refreshToken истёк	Повторный логин через loginWithEmailPassword
TOKEN_INVALID	401	Токен повреждён или поддельный	Проверьте что не обрезали/изменили токен
FORBIDDEN	403	Нет прав на операцию	Проверьте роль пользователя
CLUB_ACCESS_DENIED	403	Нет доступа к этому клубу	Проверьте привязку пользователя к клубу

Коды данных

Код	Описание	Действие
NOT_FOUND	Объект не существует или не в вашей организации	Проверьте ID и принадлежность организации
ALREADY_EXISTS	Дубликат при создании	Проверьте уникальные поля (email, phone)
VALIDATION_ERROR	Данные не прошли валидацию	Проверьте поле details в extensions
INVALID_INPUT	Неверный формат входных данных	Сверьтесь со схемой GraphQL

Коды бизнес-логики

Код	Описание	Действие
INSUFFICIENT_BALANCE	Недостаточно средств на балансе	Проверьте баланс перед операцией
SESSION_ALREADY_ACTIVE	На устройстве уже есть активная сессия	Завершите текущую сессию через endSession
DEVICE_OFFLINE	Устройство не в сети	Проверьте статус устройства через deviceStatus
TARIFF_NOT_AVAILABLE	Тариф недоступен (расписание, зона)	Проверьте условия тарифа
CLUB_CLOSED	Клуб закрыт (нет открытой смены)	Откройте смену через CRM
CLIENT_BLACKLISTED	Клиент в чёрном списке	Обратитесь к администратору клуба
PAYMENT_FAILED	Ошибка платёжного шлюза	Проверьте поле details для кода от эквайера
WEBHOOK_URL_UNREACHABLE	URL webhook недоступен при проверке	Убедитесь что endpoint отвечает на GET

Коды инфраструктуры

Код	HTTP	Описание	Действие
RATE_LIMIT_EXCEEDED	429	Превышен лимит запросов	Подождите Retry-After секунд
INTERNAL_SERVER_ERROR	500	Внутренняя ошибка	Повторите запрос. Если повторяется — в support IZI
SERVICE_UNAVAILABLE	503	Сервис временно недоступен	Exponential backoff

Обработка ошибок в коде

async function handleIZIRequest(query, variables) {
  const response = await client.request(query, variables);

  if (response.errors) {
    for (const error of response.errors) {
      const code = error.extensions?.code;

      switch (code) {
        case 'TOKEN_EXPIRED':
          await refreshTokens();
          return handleIZIRequest(query, variables); // retry

        case 'RATE_LIMIT_EXCEEDED':
          const retryAfter = error.extensions?.retryAfter || 5;
          await sleep(retryAfter * 1000);
          return handleIZIRequest(query, variables);

        case 'NOT_FOUND':
          throw new NotFoundError(error.message);

        case 'FORBIDDEN':
          throw new PermissionError(error.message);

        default:
          throw new IZIError(code, error.message, error.extensions);
      }
    }
  }

  return response.data;
}

Ошибки валидации

При VALIDATION_ERROR в extensions.details приходит список полей:

{
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "field": "input.amount",
      "message": "Must be positive number",
      "constraint": "min",
      "value": -100
    }
  ]
}

Связанные страницы

• Авторизация и токены — ошибки токенов подробнее
• Ограничения частоты запросов — про 429 и backoff
• Примеры SDK — готовые обработчики ошибок

См. также

• IZI API: обзор для разработчиков
• Основы GraphQL в IZI
• Авторизация и токены IZI API
• Ограничения частоты запросов IZI API
• Примеры SDK IZI: JavaScript и Python