Ошибки

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

Ошибки возвращаются в формате 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

Прошедшие авторизацию запросы GraphQL возвращают HTTP ответ с кодом 200 или 210 и json телом фиксированного формата. Код 210 возвращается при возникновении внутренних технических ошибок (семантический аналог 500-х ошибок HTTP), во всех остальных случая возвращается код 200.

{
  "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",
      ...
    }
  ],
  ...
}

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

Ответ на запрос с технической ошибкой времени выполнения содержит поле errors с элементом, имеющим значением INTERNAL в поле extensions.errorType. Ошибки получения одного (или более) узлов не отменяют получение данных для узлов одного с ними уровня и выше по иерархии. Успешно полученные данные возвращаются в поле data.

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

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

Иноформация об ошибках бизнес логики (отсутствие прав доступа к сущности, отсутствие сущности) для запрашиваемого узла отдается в виде объекта кастомной типизированной ошибки. Такая подмена достигается за счет использования в узле абстрактного типа 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​

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

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

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

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