Опрос и идемпотентность

Опрос — источник правды

GET /serving-tasks/?status=offered — то, как вы находите работу. Webhook’и, если зарегистрированы, являются оптимизацией задержки — но не правдой. Опрашивайте непрерывно, пока ваш парк на смене.

ETag

Каждый ответ со списком несёт ETag. Отправляйте его обратно как If-None-Match; неизменившийся список вернёт 304 Not Modified без тела. Это делает плотные циклы опроса почти бесплатными для обеих сторон — реализуйте это обязательно.

Лимиты частоты

Лимиты строгие и считаются по учётным данным:

Поверхность	Лимит
Опрос задач	60/минуту (~1/с)
Принятие/отчёт по задаче	120/минуту
Heartbeat	30/минуту

Контроллер, которому нужно больше, ведёт себя неправильно, а не занят. Ответы 429 несут Retry-After — соблюдайте его.

Идемпотентность

Каждая мутация принимает заголовок Idempotency-Key (или поле тела client_idempotency_key). Повторный запрос с тем же ключом возвращает исходный результат и ничего нового не записывает.

Всегда отправляйте его. Сеть рвётся посреди запроса; с ключом вы можете свободно повторять и никогда не примените дважды принятие или отчёт.

Используйте один ключ на действие, а не один на задачу: тот же ключ для повторов того же логического действия и новый ключ для каждого следующего. Ключ, уже потраченный на другой переход той же задачи, отклоняется с 409 (idempotency_key_reused). Ключи ограничены 128 символами.

Тела запросов тоже ограничены — необязательные объекты telemetry и summary в heartbeat должны быть JSON-объектами не более 4 КБ, вложенностью не более 5 уровней и не более чем с 50 записями в любом объекте или массиве.

Конверт ошибки

Каждый отклонённый запрос возвращает одну форму:

{ "detail": "Понятное человеку объяснение.", "code": "machine_readable_code" }

HTTP-статус	Коды
400	unknown_status, status_not_reportable, unknown_failure_code
404	task_not_found
403	правомочность парка утрачена — сертификация, активация или право по тарифу
409	already_claimed, robotics_paused, platform_frozen, arrival_dwell_pending, idempotency_key_reused, конфликты порядка task_<current_status>
410	offer_expired

Ветвитесь по code, а не по тексту detail — формулировка detail может меняться; коды контрактны.