Полная справка по всем кодам ошибок в GraphQL API Blue, организованная по категориям
Формат ответа об ошибке
GraphQL API Blue возвращает ошибки в стандартизированном формате в соответствии со спецификацией GraphQL. Когда происходит ошибка, ответ включает массив errors с подробной информацией о том, что пошло не так.
Пример ответа об ошибке
{
"errors": [
{
"message": "Todo was not found.",
"extensions": {
"code": "TODO_NOT_FOUND"
}
}
]
}
Структура ошибки
Каждый объект ошибки содержит:
- message: Читаемое человеком описание ошибки
- extensions.code: Машиночитаемый код ошибки для программной обработки
Безопасность ошибок в производстве
Blue реализует систему безопасности для раскрытия ошибок:
- Безопасные ошибки: Отображают фактические коды ошибок и сообщения клиентам
- Небезопасные ошибки: Возвращают общий
INTERNAL_SERVER_ERROR, чтобы скрыть чувствительные детали
- Ресурс не найден: Все ошибки
*_NOT_FOUND считаются безопасными и всегда раскрываются
Категории ошибок
Blue определяет 108 пользовательских кодов ошибок, организованных в следующие категории:
Ошибки аутентификации и авторизации
| Код ошибки |
Сообщение |
Описание |
UNAUTHENTICATED |
"Требуется аутентификация." |
Запрос требует аутентификации, но она не предоставлена |
FORBIDDEN |
"Вы не авторизованы." |
Аутентифицирован, но не хватает необходимых разрешений |
Ошибки "Ресурс не найден" (всего 52)
Основные ресурсы
| Код ошибки |
Сообщение |
Описание |
TODO_NOT_FOUND |
"Задача не найдена." |
Запись/задача не существует или у пользователя нет доступа |
TODO_LIST_NOT_FOUND |
"Список задач не найден." |
Список не существует или у пользователя нет доступа |
PROJECT_NOT_FOUND |
"Проект не найден." |
Проект не существует или у пользователя нет доступа |
COMPANY_NOT_FOUND |
"Компания не найдена." |
Компания не существует или у пользователя нет доступа |
USER_NOT_FOUND |
"Пользователь не найден." |
Пользователь не существует в системе |
Пользовательские поля и формы
| Код ошибки |
Сообщение |
Описание |
CUSTOM_FIELD_NOT_FOUND |
"Пользовательское поле не найдено." |
Пользовательское поле не существует |
CUSTOM_FIELD_OPTION_NOT_FOUND |
"Опция пользовательского поля не найдена." |
Опция выбора поля не существует |
FORM_NOT_FOUND |
"Форма не найдена." |
Шаблон формы не существует |
FORM_FIELD_NOT_FOUND |
"Поле формы не найдено." |
Поле формы не существует |
Компоненты проекта
| Код ошибки |
Сообщение |
Описание |
TAG_NOT_FOUND |
"Тег не найден." |
Тег не существует в проекте |
AUTOMATION_NOT_FOUND |
"Автоматизация не найдена." |
Правило автоматизации не существует |
CHART_NOT_FOUND |
"График не найден." |
График панели управления не существует |
WEBHOOK_NOT_FOUND |
"Webhook не найден." |
Конфигурация webhook не существует |
TEMPLATE_NOT_FOUND |
"Шаблон не найден." |
Шаблон проекта не существует |
Комментарии и действия
| Код ошибки |
Сообщение |
Описание |
COMMENT_NOT_FOUND |
"Комментарий не найден." |
Комментарий не существует |
ACTIVITY_NOT_FOUND |
"Действие не найдено." |
Запись в журнале действий не существует |
REACTION_NOT_FOUND |
"Реакция не найдена." |
Реакция на комментарий не существует |
Другие ресурсы
| Код ошибки |
Сообщение |
Описание |
FILE_NOT_FOUND |
"Файл не найден." |
Вложение файла не существует |
SUBSCRIPTION_NOT_FOUND |
"Подписка не найдена." |
Подписка на оплату не существует |
INVOICE_NOT_FOUND |
"Счет не найден." |
Запись счета не существует |
CHECKLIST_NOT_FOUND |
"Чек-лист не найден." |
Чек-лист не существует |
CHECKLIST_ITEM_NOT_FOUND |
"Элемент чек-листа не найден." |
Элемент чек-листа не существует |
PROJECT_ROLE_NOT_FOUND |
"Роль проекта не найдена." |
Пользовательская роль проекта не существует |
PROJECT_ACCESS_NOT_FOUND |
"Доступ к проекту не найден." |
Доступ пользователя к проекту не существует |
NOTIFICATION_NOT_FOUND |
"Уведомление не найдено." |
Уведомление не существует |
DASHBOARD_NOT_FOUND |
"Панель управления не найдена." |
Панель управления не существует |
KEY_NOT_FOUND |
"Ключ не найден." |
Ключ настроек не существует |
Ошибки валидации
| Код ошибки |
Сообщение |
Описание |
BAD_USER_INPUT |
"Неверный ввод." |
Общая ошибка валидации ввода |
VALIDATION_ERROR |
"Неверные параметры" |
Параметры запроса не прошли валидацию |
BAD_EMAIL |
"Вы должны ввести действительный адрес электронной почты." |
Неверный формат электронной почты |
INVALID_IDS |
"Неверные идентификаторы." |
Один или несколько идентификаторов в запросе неверны |
PHONE_INVALID |
"Телефон неверный." |
Неверный формат номера телефона |
URL_INVALID |
"URL неверный." |
Неверный формат URL |
INVALID_RECURRING_DUE_DATE |
"Неверная дата выполнения для повторяющейся задачи" |
Ошибка валидации даты повторяющейся задачи |
INVALID_COLOR |
"Неверный цвет" |
Значение цвета не соответствует ожидаемому формату |
Ошибки бизнес-логики
Ограничения и квоты
| Код ошибки |
Сообщение |
Описание |
COMPANY_LIMIT |
"Вы достигли лимита компаний для вашей учетной записи." |
Достигнут максимальный лимит компаний |
PROJECT_LIMIT |
"Вы достигли лимита проектов для вашей компании." |
Достигнут максимальный лимит проектов |
USER_LIMIT |
"Вы достигли лимита пользователей для вашей компании." |
Достигнут максимальный лимит пользователей |
PROJECT_TEMPLATE_LIMIT |
"Вы достигли лимита шаблонов для вашей компании." |
Достигнут максимальный лимит шаблонов |
CUSTOM_FIELD_LIMIT |
"Достигнут лимит пользовательских полей." |
Достигнут максимальный лимит пользовательских полей |
TODO_LIST_LIMIT |
"Вы достигли лимита списков для вашего проекта." |
Максимальное количество списков на проект |
TOO_MANY_TODOS |
"Слишком много задач." |
Превышен лимит записей |
TOO_MANY_OPTIONS |
"Слишком много опций." |
Превышен лимит опций выбора |
MAX_FILE_SIZE |
"Максимальный размер файла 4.8 ГБ" |
Превышен лимит размера загружаемого файла |
Конфликты ресурсов
| Код ошибки |
Сообщение |
Описание |
TAG_ALREADY_EXISTS |
"Тег уже существует." |
Тег с таким же именем существует в проекте |
COMPANY_SLUG_ALREADY_EXISTS |
"Компания уже существует." |
Слаг/URL компании занят |
USER_ALREADY_EXISTS |
"Пользователь уже существует." |
Электронная почта пользователя уже зарегистрирована |
ALREADY_INVITED |
"Пользователь уже приглашен." |
У пользователя уже есть ожидающее приглашение |
USER_ALREADY_IN_PROJECT |
"Пользователь уже в этом проекте." |
У пользователя уже есть доступ к проекту |
FILE_TYPE_NOT_ALLOWED |
"Тип файла не разрешен." |
Загруженный тип файла ограничен |
Ошибки разрешений и доступа
| Код ошибки |
Сообщение |
Описание |
UNABLE_TO_DELETE_ONLY_ADMIN |
"Невозможно удалить единственного администратора в компании." |
Нельзя удалить последнего администратора |
UNABLE_TO_UPDATE_OWNER |
"Невозможно обновить ВЛАДЕЛЬЦА." |
Невозможно изменить разрешения владельца |
TODO_LIST_IS_HIDDEN |
"Список задач скрыт." |
Список скрыт от роли пользователя |
COMPANY_NOT_ACTIVE |
"Компания не активна." |
Подписка компании неактивна |
PROJECT_NOT_ACTIVE |
"Проект не активен." |
Проект архивирован/неактивен |
Ошибки целостности данных
| Код ошибки |
Сообщение |
Описание |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"Невозможно удалить список с задачами." |
Список должен быть пустым для удаления |
UNABLE_TO_DELTE_FILE |
"Невозможно удалить файл." |
Удаление файла не удалось (опечатка в коде) |
UNABLE_TO_MOVE_TODO |
"Невозможно переместить задачу." |
Невозможно переместить запись между списками |
DEPENDENCY_HAS_DEPENDENCY |
"Зависимость имеет зависимость" |
Обнаружена циклическая зависимость |
TODO_DEPENDS_ON_ITSELF |
"Задача зависит от самой себя" |
Само-ссылающаяся зависимость |
Ошибки Stripe/платежей
| Код ошибки |
Сообщение |
Описание |
STRIPE_CREATING_CUSTOMER |
"Ошибка при создании клиента в Stripe." |
Создание клиента Stripe не удалось |
STRIPE_ALREADY_SUBSCRIBED |
"Уже подписан." |
Активная подписка существует |
STRIPE_MISSING_PAYMENT_METHOD |
"Отсутствует способ оплаты." |
Нет способа оплаты в файле |
STRIPE_CREATING_SUBSCRIPTION |
"Ошибка при создании подписки в Stripe." |
Создание подписки не удалось |
STRIPE_UPDATING_SUBSCRIPTION |
"Ошибка при обновлении подписки в Stripe." |
Обновление подписки не удалось |
STRIPE_CHECKOUT_SESSION |
"Ошибка при создании сессии оформления заказа в Stripe." |
Создание сессии оформления заказа не удалось |
STRIPE_CUSTOMER_PORTAL |
"Ошибка при создании портала клиента в Stripe." |
Создание сессии портала не удалось |
STRIPE_TAX_ID |
"Не удалось сохранить налоговый идентификатор" |
Валидация/сохранение налогового идентификатора не удалось |
PAYMENT_REQUIRED |
"Требуется оплата." |
Функция требует активной подписки |
NO_PAYMENT_REQUIRED |
"Оплата не требуется." |
Оплата не нужна для операции |
Ошибки аутентификации и сессии
| Код ошибки |
Сообщение |
Описание |
INVALID_CREDENTIALS |
"Неверные учетные данные." |
Неправильное имя пользователя/пароль |
EXPIRED_RESET_TOKEN |
"Токен сброса истек." |
Токен сброса пароля истек |
OAUTH_FAILED |
"Процесс OAuth не удался." |
Аутентификация OAuth не удалась |
SAML_NOT_ENABLED |
"SSO (SAML) не включен." |
SAML SSO не настроен |
SSO_AUTO_PROVISION_DISABLED |
"Авто-пр Provision отключен." |
Невозможно автоматически создать пользователей SSO |
Ограничение частоты
Ограничение частоты обрабатывается пакетом graphql-rate-limit с различными конфигурациями:
| Тип ограничения |
Окно |
Максимум запросов |
Применяется к |
| Standard |
60s |
500 |
Most queries/mutations |
| Sensitive |
300s |
10 |
Password reset, auth operations |
| Expensive |
60s |
20 |
Complex queries, bulk operations |
| Search |
60s |
60 |
Search operations |
| File Upload |
60s |
100 |
File upload operations |
Когда вы достигаете ограничения частоты, вы получите стандартную ошибку GraphQL с сообщением, указывающим на превышение лимита.
Системные и внутренние ошибки
| Код ошибки |
Сообщение |
Описание |
INTERNAL_SERVER_ERROR |
"Внутренняя ошибка сервера." |
Общая ошибка для небезопасных ошибок в производстве |
UNKNOWN_ERROR |
"Неизвестная ошибка." |
Произошла неожиданная ошибка |
RESOLVER_NOT_FOUND |
"Решатель не найден" |
Отсутствует GraphQL решатель |
FIELD_NOT_IN_SCHEMA |
"Поле отсутствует в схеме" |
Запрашиваемое поле не существует |
Рекомендации по обработке ошибок
Обработка на стороне клиента
try {
const result = await client.mutate({
mutation: CREATE_TODO,
variables: { input }
});
} catch (error) {
if (error.graphQLErrors?.length > 0) {
const errorCode = error.graphQLErrors[0].extensions?.code;
switch (errorCode) {
case 'UNAUTHENTICATED':
// Redirect to login
break;
case 'TODO_NOT_FOUND':
// Show "Record not found" message
break;
case 'VALIDATION_ERROR':
// Display validation errors
break;
default:
// Show generic error message
}
}
}
Распространенные сценарии ошибок
- Требуется аутентификация:
UNAUTHENTICATED - Пользователь должен войти в систему
- Доступ запрещен:
FORBIDDEN - У пользователя нет необходимых ролей/разрешений
- Ресурс не найден:
*_NOT_FOUND - Ресурс не существует или пользователь не может получить к нему доступ
- Ошибка валидации:
VALIDATION_ERROR, BAD_USER_INPUT - Проверьте параметры ввода
- Превышен лимит частоты: Проверьте заголовки ограничения частоты и реализуйте откат
- Требуется оплата:
PAYMENT_REQUIRED - Функция требует подписки
Связанная документация