Ошибки

Ошибки предвалидации запроса, внутренние ошибки сервера

Ошибки возвращаются в формате json

{
  "type": "...",
  "detail": "..."
}

HTTP code	type	detail	Описание
400	invalid_request		невалидный запрос (например, заголовок Authorization отсутствует либо прислан в невалидном формате, невалидное тело запроса)
400	invalid_request	graphql_query_not_found	в теле запроса отсутствует обязательное поле "query"
401	invalid_token	token_not_found	не найден токен доступа
401	invalid_token	token_expired	токен доступа просрочен
403	api_access	insufficient_permissions	отсутствует право использования API
403	api_access	authorisation_not_found	авторизация в Talantix истекла или была отозвана, авторизируйтесь в системе Talantix
403	api_access	access_blocked	доступ к API заблокирован, обратитесь в службу поддержки
404	not_found		запрос несуществующего ресурса
413	request_entity_too_large		тело запроса превышает установленный лимит
429	too_many_requests		превышено допустимое количество запросов в единицу времени
500	internal_server_error		внутренняя ошибка сервера

Ошибки выполнения запроса GraphQL

Результаты выполнения операций query и mutation возвращаются с HTTP-кодом 200, 210 или 269 и JSON-телом фиксированного формата. Статус относится ко всему ответу и определяется по типам ошибок в итоговом массиве errors.

HTTP-код	Условие
200	В `errors` нет `INTERNAL` и `EXTERNAL_SYSTEM_ERROR`. Возможны ошибки валидации запроса и предметные ошибки в `data`.
210	В `errors` есть хотя бы одна ошибка с `extensions.errorType = INTERNAL`, в том числе вместе с `EXTERNAL_SYSTEM_ERROR`.
269	В `errors` есть хотя бы одна ошибка с `extensions.errorType = EXTERNAL_SYSTEM_ERROR` и нет `INTERNAL`.

Клиент должен разбирать тело ответа для всех трёх статусов. Код семейства 2xx сам по себе не означает, что все поля получены или действие выполнено успешно: необходимо проверять errors и предметный результат в data. Для распознавания системных и внешних ошибок используйте extensions.errorType, а не текст message. При наличии ошибок сохраняйте доступные частичные данные из data.

{
  "errors": [
    {
      "message": ...,
      "locations": [
        {
          "line": ...,
          "column": ...
        }
      ],
      "path": ...,
      "extensions": {
        "errorType": ...
      }
    }
  ],
  "data": ...,
  "dataPresent": ...
}

где

errors - список технических ошибок, произошедших в процессе выполнения запроса (ошибки в коде, отказы внешних систем, таймауты походов, ошибка валидации данных запроса и т.д.). Пустой список означает отсутствие таких ошибок; предметные ошибки могут возвращаться в data;
message - текст и описание ошибки;
locations - массив расположения невалидных полей запроса либо полей, получении которых вызывало ошибку;
path - путь к узлу, получение которого вызвало ошибку;
extensions - дополнительная информация об ошибке;
data - полученные данные либо null;
dataPresent - true или false в зависимости от того, были получены какие-либо данные в результате запроса или нет.

Ошибки валидации запроса

Запрос, содержащий в поле query невалидные данные (ошибки в синтаксисе, несуществующие поля), возвращает ответ

{
  "errors": [
    {
      "message": "Validation error (FieldUndefined@[me/idd]) : Field 'idd' in type 'Me' is undefined",
      "locations": [
        {
          "line": 5,
          "column": 5
        }
      ],
      "path": null,
      "extensions": {}
    }
  ],
  "data": null,
  "dataPresent": false
}

Ошибки сложности запроса

Запрос с обходом большого количества узлов (в т.ч. вложенных списков узлов и их комбинаций) может создавать значительную нагрузку на систему. Поэтому сложность каждого запроса анализируется перед выполнением и, в случае превышения порогового значения, возвращается ответ с ошибкой

{
  "errors": [
    {
      "message": "Requested operation exceeds the permitted complexity limit: 2650 > 2499",
      ...
    }
  ],
  ...
}

Ошибки числа корневых полей

В одном запросе внешнего API допускается не более одного корневого поля (root selection) на operation. Алиасы одного и того же поля считаются отдельно; повторы одного ключа (в том числе через фрагменты) — нет. Служебные поля __typename, __schema и __type в лимит не входят.

{
  "errors": [
    {
      "message": "Requested operation exceeds the permitted root selection limit of 1",
      ...
    }
  ],
  ...
}

Ошибки выполнения запроса технического характера

Необработанное исключение в резолвере query или mutation, не классифицированное как внешний отказ, возвращается в errors с extensions.errorType = INTERNAL и HTTP-кодом 210. Сообщение Internal error не содержит деталей исходного исключения. Доступные частичные данные возвращаются в data с учётом правил GraphQL для полей non-null.

{
  "errors": [
    {
      "message": "Internal error",
      "locations": [
        {
          "line": 2,
          "column": 3,
          "sourceName": null
        }
      ],
      "path": ["persons.items.personalDataAgreement"],
      "extensions": {
        "errorType": "INTERNAL"
      }
    }
  ],
  "data": {
    "persons": {
      "items": [
        {
          "id": 1
        }
      ]
    }
  },
  "extensions": null,
  "dataPresent": true
}

Ошибки внешних систем

Распознанный отказ внешней системы возвращается в errors с extensions.errorType = EXTERNAL_SYSTEM_ERROR. Если в итоговом errors нет INTERNAL, HTTP-код ответа — 269. Фрагмент элемента массива errors:

{
  "message": "External system error",
  "extensions": {
    "errorType": "EXTERNAL_SYSTEM_ERROR"
  }
}

Как и для INTERNAL, поле path связывает ошибку с узлом ответа, а доступные частичные данные остаются в data. При одновременном наличии INTERNAL и EXTERNAL_SYSTEM_ERROR возвращается HTTP 210 независимо от порядка ошибок; сведения о внешнем отказе сохраняются в errors.

Этот тип обозначает классификацию отказа внешнего вызова и не гарантирует отсутствие ошибки на стороне Talantix. Сообщение не содержит исходного текста ошибки внешней системы.

Ошибки бизнес логики

Иноформация об ошибках бизнес логики (отсутствие прав доступа к сущности, отсутствие сущности) для запрашиваемого узла отдается в виде объекта кастомной типизированной ошибки. Такая подмена достигается за счет использования в узле абстрактного типа union GraphQL. Например, запрос менеджера по id с получением ошибки выглядит следующим образом

graphql
cURL

query ManagerWithError {
  manager(id: 5) {
    __typename
    ... on CompanyManager {
      id
    }
    ... on ManagerError {
      errorType
      message
    }
  }
}

curl https://api.talantix.ru/graphql \
 -X POST \
-H "Content-Type: application/json" \
-H "User-Agent: api-doc-agent" \
-H "Authorization: Bearer <your access token>" \
-d "{\"query\":\"query ManagerWithError {\\n  manager(id: 5) {\\n    __typename\\n    ... on CompanyManager {\\n      id\\n    }\\n    ... on ManagerError {\\n      errorType\\n      message\\n    }\\n  }\\n}\"}"

Посмотреть в playground

с ответом

{
  "errors": [],
  "data": {
    "manager": {
      "__typename": "ManagerError",
      "errorType": "NOT_FOUND",
      "message": null
    }
  },
  "dataPresent": true
}

Таким образом, ошибки бизнес логики возвращаются вместе с остальными данными в поле data, в то время как поле errors содержит только технические ошибки выполнения запроса.

Ошибки

Ошибки предвалидации запроса, внутренние ошибки сервера​

Ошибки выполнения запроса GraphQL​

Ошибки валидации запроса​

Ошибки сложности запроса​

Ошибки числа корневых полей​

Ошибки выполнения запроса технического характера​

Ошибки внешних систем​

Ошибки бизнес логики​