Ошибки API и повтор запросов
Сначала проверьте HTTP-статус ответа. В JSON могут быть statusCode, message и error. Поле message содержит пояснение или список ошибок отдельных полей. Не используйте текст пояснения как постоянный код: он зависит от операции.
Например, запрос без API-ключа возвращает:
{
"message": "API key is missing",
"error": "Unauthorized",
"statusCode": 401
}Что делать при ошибке
| HTTP-статус | Что произошло | Следующий шаг |
|---|---|---|
400 | Запрос не соответствует допустимому формату | Сверьте поля, типы, даты и обязательные значения со схемой OpenAPI. Исправьте запрос перед повтором. |
401 | Ключ отсутствует, недействителен, отозван или истёк | Проверьте X-API-Key и адрес своего портала. При необходимости получите новый ключ у администратора. |
403 | Недостаточно прав или операция недоступна | Сверьте права ключа и права его создателя. Повтор того же запроса без изменения доступа не поможет. |
404 | Запись или метод недоступны по указанному адресу | Проверьте идентификатор, адрес портала и наличие метода в OpenAPI. |
409 | Конфликт версии, состояния или ключа повторного запроса | Загрузите актуальную запись. Для изменения используйте её текущую версию; не подставляйте новый ключ повторного запроса, пока не выяснили результат предыдущего. |
429 | Превышен лимит запросов | Подождите время из Retry-After, затем повторите запрос. |
5xx | Сервер не смог обработать запрос | Сохраните код ответа и время. Проверьте результат изменяющей операции перед повтором; при повторяющейся ошибке обратитесь в поддержку. |
Успешные ответы тоже различаются: 200 означает выполненную операцию, 201 — создание записи, 202 — приём задания. Для генерации документа после 202 нужно отдельно проверить состояние задания и получить результат.
Лимит запросов
При превышении лимита Integration API возвращает:
{
"statusCode": 429,
"error": "rate_limited",
"message": "Public API rate limit exceeded",
"limit": 300,
"remaining": 0,
"resetInSeconds": 17
}Числа в примере условные. Ориентируйтесь на заголовки конкретного ответа: Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset и RateLimit-Policy. Совместимые заголовки X-RateLimit-* также доступны.
Не отправляйте запросы в непрерывном цикле после отказа. Если несколько процессов используют один ключ, учитывайте их запросы совместно.
Если соединение оборвалось
Отсутствие ответа не доказывает, что запись не создана. Для операций, в которых предусмотрен Idempotency-Key, повторяйте запрос с прежним ключом и тем же телом. Новый ключ может означать новую операцию.
Если метод не поддерживает такой ключ, сначала проверьте результат чтением записи. Не повторяйте создание автоматически только из-за сетевой ошибки.
Что передать в поддержку
Укажите время ошибки с часовым поясом, HTTP-статус, метод и ожидаемый результат. Приложите пример запроса с условными значениями, если он нужен для объяснения.
Удалите из примера API-ключ, секрет подписи, персональные данные, содержимое документов и ссылки, которые дают доступ к ним. Не отправляйте полный журнал обмена без проверки его содержимого.