Ошибки и отказоустойчивость

Профессиональная интеграция не рассматривает ошибки как некую единую неделимую проблему. Ошибки идентификации, прав доступа, областей видимости тенанта, валидации данных и временные сбои сервиса возвращают различные HTTP-коды состояния.

Как интерпретировать типы ошибок

401 Unauthorized: ошибка аутентификации. Токен доступа отсутствует или истек. Вашему бэкенду необходимо запросить новый токен с помощью client credentials.
403 Forbidden: доступ запрещен. Отсутствует необходимый scope или доступ к запрашиваемому аккаунту.
404 Not Found: ресурс не существует либо находится за пределами границы вашего тенанта.
400 Bad Request: ошибка валидации. Указывает на пропущенные, неизвестные или нарушающие бизнес-логику поля.
409 Conflict: один и тот же Idempotency-Key использован повторно с другим телом запроса, либо ресурс не может выполнить операцию в текущем состоянии.
429 Too Many Requests: превышен лимит частоты запросов. Подождите количество секунд, указанное в заголовке ответа Retry-After.
500/502/503/504: сервер или шлюз временно не смогли обработать запрос. Повторяйте только безопасные/идемпотентные операции, используя экспоненциальную задержку с джиттером (jitter).

Почему важна идемпотентность

Ответ на POST-запрос может потеряться в сети, даже если запись была успешно создана на сервере, оставляя клиент в неопределенности. Если вы передаете уникальный Idempotency-Key длиной от 8 до 128 символов в эндпоинты создания записей, повторный запрос с тем же ключом и тем же телом не создаст дубликат записи. Повторно воспроизведенный ответ будет содержать заголовок Idempotency-Replayed: true.

Заголовки ограничений (Rate Limits)

Каждый ответ сообщает о текущем состоянии лимитов с помощью трех заголовков:

X-RateLimit-Limit: разрешенное количество запросов за временное окно.
X-RateLimit-Remaining: остаток доступных запросов в текущем окне.
X-RateLimit-Reset: количество секунд до сброса квоты.

Пагинация

Эндпоинты списков возвращают массив data, а также объекты meta и links. Считывайте следующую страницу из links.next, а не увеличивайте номер страницы вручную, и используйте meta.total_pages как условие завершения. Максимальный размер страницы — 100 элементов.