Ошибки
Типичная форма ошибки Open API и коды состояния.
Ошибок
Ошибки Open API используют тела ответа JSON, когда запрос достигает уровня API. Сбои сети, сбои CDN и прерывания двоичных ответов могут иметь не такую точную форму, поэтому ваш клиент должен обрабатывать как структурированные ошибки API, так и ошибки транспорта.
Каждая конечная точка использует один и тот же контекст аутентификации носителя:
Authorization: Bearer KITTA_API_KEY{
"code": "invalid_request",
"message": "The request payload is invalid.",
"requestId": "req_xxx"
}Коды состояния
| Статус | Значение | Типичное действие |
|---|---|---|
400 | Недопустимое тело запроса, параметр пути, параметр запроса или URL-адрес носителя | Исправьте запрос перед повторной попыткой |
401 | Ключ API отсутствует, имеет неверный формат, отозван или отключен | Остановить повторные попытки и обновить учетные данные |
402 | Недостаточно кредитов, квота API или распределение поставщика | Остановить пакетную обработку и показать состояние выставления счетов |
404 | Идентификатор ресурса неизвестен для аутентифицированной учетной записи | Обновить локальные записи |
409 | Ресурс находится в состоянии, конфликтующем с операцией | Подождите или удалите зависимости |
422 | Медиафайл принят, но не может быть обработан | Запросите другие входные носители |
429 | Превышен лимит скорости | Повторить попытку с экспоненциальной задержкой |
500 | Ошибка сервера | Повторите попытку небольшое количество раз и зарегистрируйте requestId |
Регистрация запросов
Зарегистрируйте конечную точку, метод HTTP, статус, code, requestId и собственный внутренний идентификатор задания. Не регистрируйте ключи носителя API, полный пользовательский текст или URL-адреса частных носителей, если это явно не разрешено вашей политикой конфиденциальности и рабочим процессом поддержки.
Для асинхронных конечных точек включите в журналы как идентификатор задачи API, так и идентификатор внутренней базы данных. Это позволяет согласовывать повторные попытки без создания дублирующей работы.
Выставление счетов и кредиты
Не каждая ошибка имеет одинаковое значение для выставления счетов. Сбои проверки обычно случаются до начала работы с носителем. Сбои обработки могут произойти после того, как задача была принята. При возникновении вопросов по выставлению счетов, возникающих у пользователей, сравните статус задачи со свежим чтением Профиля вместо того, чтобы делать выводы о стоимости только на основании статуса HTTP.
Политика повтора
Повторите попытку 429 и некоторых ответов 500 с отсрочкой. Не повторяйте слепо 400, 401 или 402; для них требуются изменения запроса, учетных данных или выставления счетов. Для создания конечных точек сохраните возвращенный идентификатор, прежде чем повторять любую последующую операцию.