Ошибки и безопасные повторы
Как различать ошибки, повторять временно неудачные запросы и не создавать дубли.
Результат
После настройки ваша система сможет отличать ошибку в запросе от временного сбоя, безопасно повторять операции и не создавать дубли.
Как выглядит ошибка
Integration API возвращает ошибки в формате application/problem+json:
Пример ответа
{
"type": "about:blank",
"title": "Integration API request failed",
"status": 409,
"detail": "Idempotency-Key was already used with another request.",
"instance": "/v1/tickets/f5b382ad-d8e7-4c3f-99bb-aa2769d85be1/messages",
"traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}
В программной логике ориентируйтесь прежде всего на HTTP-код и выполняемую операцию. Текст detail нужен человеку для диагностики и со временем может уточняться.
При обращении в поддержку передайте traceId, время запроса и название среды. Никогда не отправляйте API-ключ.
Что делать с разными кодами
| Код | Причина | Что делать |
|---|---|---|
400 | Неверный формат запроса или ключа идемпотентности | Исправить запрос и отправить снова |
401 | Ключ отсутствует, неверен или отозван | Заменить или проверить ключ |
403 | Нет нужного разрешения | Проверить разрешения ключа (scopes) и подключённые разделы API |
404 | Ресурс не найден или недоступен этому ключу | Проверить среду и идентификатор; не повторять автоматически |
409 | Конфликт состояния или ключа идемпотентности | Разобрать конфликт перед новым запросом |
422 | Поля имеют верный формат, но нарушают правило операции | Исправить данные |
429 | Превышен лимит запросов | Подождать, учитывая Retry-After |
500 | Временный внутренний сбой | Повторить ограниченное число раз |
Как защита от дублей работает
Каждый запрос, который изменяет данные, должен содержать Idempotency-Key. Это ваш стабильный идентификатор одной бизнес-операции.
Требования к ключу:
- длина от 1 до 200 символов;
- один ключ соответствует только одной операции;
- при сетевой неопределённости повторяется тот же ключ и то же тело;
- ключ нельзя использовать для другого запроса или изменённого тела.
Yario хранит результат 24 часа. В своей системе храните связь операции, ключа и результата не меньше этого срока.
Если одинаковые запросы придут одновременно, Yario выполнит действие один раз и вернёт один результат. Если при том же ключе тела отличаются, конфликтующий запрос получит 409.
Какие запросы можно повторять
Автоматически повторяйте только:
- сетевые ошибки;
408;429;- ответы
5xx.
Используйте тот же Idempotency-Key и то же тело. Увеличивайте паузу между попытками, добавляйте небольшую случайную задержку и ограничивайте общее число повторов.
Подходящий пример задержек: 1, 2, 4, 8, 16 и 30 секунд. Для 429 сначала используйте значение Retry-After, если оно есть.
После исчерпания попыток переведите операцию в ручную диагностику, а не запускайте бесконечный цикл.
Ограничения
- до 600 запросов в минуту на экземпляр сервиса;
- тело публичного запроса — до 1 МиБ;
- текст сообщения — до 20 000 символов;
- заголовок обращения — до 300 символов;
- выдача сообщений — до 200 элементов за запрос.
Большие файлы передавайте защищённой ссылкой во вложении, а не внутри JSON.
Как понять, что всё работает
Проверьте повтор успешного запроса, конфликт изменённого тела, ответ 429 с задержкой и ограниченный повтор временного 5xx. Убедитесь, что ни один сценарий не создаёт второе обращение или сообщение.
Навигация: начало работы · безопасность ключей · обращения и сообщения · уведомления от Yario · тестирование