Ошибки

Класс ошибки задаёт HTTP-статус, а точную причину несёт строковый код. Он приходит в заголовке X-Error-Reason и дублируется в теле ответа. Тело — стандартный google.rpc.Status, поэтому поле code в нём числовое (код gRPC), а не строка.

HTTP/1.1 403 Forbidden
Content-Type: application/json
X-Error-Reason: DEVELOPER.SCOPE_INSUFFICIENT

{
  "code": 7,
  "message": "the API key is missing the required scope: employees:read",
  "details": [
    {
      "@type": "type.googleapis.com/google.rpc.ErrorInfo",
      "reason": "DEVELOPER_SCOPE_INSUFFICIENT",
      "domain": "doodocs.people",
      "metadata": { "code": "DEVELOPER.SCOPE_INSUFFICIENT" }
    }
  ]
}

Для программной обработки ветвитесь по заголовку X-Error-Reason. Если заголовки недоступны, тот же код лежит в details[].metadata.code, а details[].reason — это он же с точками, заменёнными на подчёркивания. Текст message предназначен человеку и может меняться — не сопоставляйте с ним.

Не ветвитесь по числовому code в теле: это код gRPC, а не код ошибки Doodocs. Значение 7 в примере означает PermissionDenied, а не «недостаточно областей».

Для ошибок «ресурс не найден» в details добавляется второй элемент google.rpc.ResourceInfo с полями resourceType и resourceName.

Коды состояния

HTTP	Значение
400	Некорректный запрос (неизвестный параметр, фильтр или токен)
401	Ключ отсутствует, недействителен или отозван
403	Ключу не хватает области доступа, либо функция не включена
404	Ресурс не найден (или недоступен вашему ключу)
409	Конфликт: повторный `Idempotency-Key` в Ingest
429	Превышен лимит запросов
500	Внутренняя ошибка сервера

Коды ошибок

Ключ и доступ

Код	HTTP	Когда возникает
`INTEGRATION.API_KEY_INVALID`	401	Ключ не принят: отсутствует, отозван или неизвестен
`DEVELOPER.SCOPE_INSUFFICIENT`	403	У ключа нет области, которую требует эндпоинт
`FEATURE_FLAG.NOT_AVAILABLE`	403	Developer API не включён для тенанта
`INTEGRATION.API_KEY_SCOPE_INVALID`	400	При создании ключа передана неизвестная область

Списки и параметры

Код	HTTP	Когда возникает
`DEVELOPER.INVALID_PAGE_TOKEN`	400	`page_token` повреждён или не соответствует фильтрам
`DEVELOPER.INVALID_EXPAND`	400	В `expand` передано неизвестное имя
`DEVELOPER.INVALID_STATUS`	400	В `status` передано неизвестное значение
`DEVELOPER.INVALID_ARGUMENT`	400	Тело запроса не проходит проверку (например `template_values` не соответствует схеме)

Сотрудники

Код	HTTP	Когда возникает
`EMPLOYEE_NOT_FOUND`	404	Сотрудник не существует или недоступен ключу

Документы

Код	HTTP	Когда возникает
`DOCUMENT_NOT_FOUND`	404	Документ не существует или недоступен ключу
`DOCUMENT_TEMPLATE_NOT_FOUND`	404	Шаблон не существует, не активен или без опубликованной версии
`DOCUMENT_FILE_NOT_FOUND`	404	У документа нет файла запрошенного `file_type`
`DOCUMENT_INITIATOR_NOT_FOUND`	404	Владелец ключа не является сотрудником этого тенанта
`DEVELOPER.INVALID_SIGN_METHOD`	400	Не передан или не поддерживается `sign_method`

Файлы

Код	HTTP	Когда возникает
`FILE_NOT_FOUND`	404	Файл не существует или недоступен ключу
`FILE.INVALID_CONTENT_TYPE`	400	Тип содержимого не поддерживается
`FILE.INVALID_SIZE`	400	Размер вне допустимых границ
`FILE.PENDING_LIMIT_EXCEEDED`	400	Слишком много неподтверждённых загрузок
`FILE.NOT_UPLOADED`	400	`_confirm` вызван до фактической загрузки в хранилище
`FILE.SIZE_MISMATCH`	400	Загруженный файл больше объявленного `size_bytes`
`FILE.ALREADY_LINKED`	400	Файл уже привязан к другой сущности
`FILE.IN_USE`	400	Файл используется и не может быть изменён
`FILE.NOT_FILE_OWNER`	403	Файл загружен другим владельцем ключа

Вебхуки

Код	HTTP	Когда возникает
`WEBHOOK_NOT_FOUND`	404	Подписка не существует
`DEVELOPER.WEBHOOK_URL_INVALID`	400	URL не `https` или указывает на приватный адрес
`DEVELOPER.WEBHOOK_EVENT_INVALID`	400	Передан неизвестный тип события
`DEVELOPER.WEBHOOK_EVENT_TYPES_REQUIRED`	400	Не передано ни одного типа события
`DEVELOPER.WEBHOOK_ROTATION_IN_PROGRESS`	409	Прежний секрет ещё внутри своего окна
`WEBHOOK_DELIVERY_NOT_FOUND`	404	Доставки с таким идентификатором нет
`DEVELOPER.WEBHOOK_DELIVERY_NOT_REDELIVERABLE`	400	Подписка отключена, повтор невозможен

Ingest

Код	HTTP	Когда возникает
`INTEGRATION.IDEMPOTENCY_REQUIRED`	400	Заголовок `Idempotency-Key` не передан
`INTEGRATION.IDEMPOTENCY_REQUIRED`	409	Загрузка с таким `Idempotency-Key` уже принята
`DEVELOPER.IDEMPOTENCY_KEY_CONFLICT`	409	Ключ уже использован с другим телом запроса
`DEVELOPER.IDEMPOTENCY_IN_PROGRESS`	409	Первый запрос с этим ключом ещё выполняется

Почему 404, а не 403

Чтобы API нельзя было использовать как оракул, «не существует», «нет доступа» и «черновик/удалён» для одиночных ресурсов возвращают одинаковый 404 — например EMPLOYEE_NOT_FOUND для сотрудника и DOCUMENT_NOT_FOUND для документа. По коду ответа нельзя выяснить, существует ли скрытый от вас ресурс.

Ограничения preview

Ошибка ограничителя частоты (429) приходит без X-Error-Reason и с пустым details. Опознавайте её по статусу, а паузу берите из заголовка Retry-After.
Опечатка в имени query-параметра обрабатывается транскодером до попадания в API и возвращает 500 с текстом unknown field in field path. Неизвестное значение параметра при этом даёт корректный 400.

Обзор

Endpoints

Коды состояния

Коды ошибок

Ключ и доступ

Списки и параметры

Сотрудники

Документы

Файлы

Вебхуки

Ingest

Почему 404, а не 403

Ограничения preview

​Коды состояния

​Коды ошибок

​Ключ и доступ

​Списки и параметры

​Сотрудники

​Документы

​Файлы

​Вебхуки

​Ingest

​Почему 404, а не 403

​Ограничения preview

Коды состояния

Коды ошибок

Ключ и доступ

Списки и параметры

Сотрудники

Документы

Файлы

Вебхуки

Ingest

Почему 404, а не 403

Ограничения preview