Надёжность и ошибки

Формат ошибки

{
  "error_code": "permission_denied",
  "message": "The current identity cannot update this competition.",
  "request_id": "req_01J..."
}

Принимайте решения по HTTP-статусу и error_code. Поле message предназначено человеку и может уточняться без изменения контракта.

Защита от повторного выполнения

Для поддерживаемых мутаций передайте уникальный ключ:

Idempotency-Key: 0f6176bc-735f-4cbb-bbfd-a34610470ee8

Повтор для того же пользователя, операции, ключа и тела запроса возвращает исходный результат. Тот же ключ с другим телом отклоняется. Храните ключ вместе с локальной операцией до получения однозначного результата.

Повторы после ошибки

Повторяйте только временные ошибки: 429, 502, 503, 504 и сетевой тайм-аут. Учитывайте Retry-After, увеличивайте паузу с каждым повтором и задавайте общий лимит времени. Не повторяйте 400, 401, 403, 404 и ошибки проверки без изменения запроса.

Лимиты запросов

Стандартные лимиты описаны в контракте и могут зависеть от типа токена. Ответ 429 содержит безопасную ошибку; частые повторы замедляют восстановление.

Страницы результатов

Коллекции принимают page и page_size. Не предполагайте, что один ответ содержит все элементы или что порядок без явно заданной сортировки стабилен между изменениями.

Поиск запроса в журналах

Сохраняйте request_id рядом с названием операции и временем запроса. Не записывайте токен, ссылки загрузки, содержимое файлов или приватные ответы в обычные журналы приложения.