Лимиты и ошибки

Ограничение частоты

120 запросов в минуту на ключ — значение по умолчанию, на конкретной установке оно может отличаться. Лимит считается по префиксу ключа, поэтому два разных ключа дают удвоенный лимит.

При превышении возвращается 429 с заголовком Retry-After (секунды):

HTTP/1.1 429 Too Many Requests
Retry-After: 41

{"detail": "Request was throttled. Expected available in 41 seconds."}

Обрабатывайте 429 и делайте паузу на указанное время. При массовой выгрузке используйте bulk вместо отправки заказов по одному.

Коды ответов

Код	Значение
200	Успех
201	Заказ создан
202	Задание принято в работу
400	Ошибка в данных запроса
401	Проблема с ключом
403	Ключу не хватает разрешения
404	Не найдено (в том числе чужие данные)
405	Метод не поддерживается
409	Действие невозможно в текущем статусе
429	Превышен лимит частоты
500	Ошибка на стороне платформы

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

Единого формата нет — встречаются три варианта:

{"address": ["This field may not be blank."]}   // ошибки по полям
{"detail": "The order selection is empty."}      // одна строка
{"detail": ["Provide at least one of order_ids or external_ids."]}  // список

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

Не всякий ответ — JSON. Если в адресе отслеживания передать нечисловой идентификатор (например /routes/abc/tracking/), запрос не дойдёт до обработчика и вернётся 404 в виде HTML-страницы, а не {"detail": ...}. Разбор ответа должен это переживать: сначала проверяйте код и Content-Type, потом разбирайте тело.

Изоляция данных

Ключ работает строго в пределах вашей компании. Обращение к чужому объекту возвращает 404, а не 403 — существование чужих данных не раскрывается.

Повторная отправка

Заголовок идемпотентности не поддерживается.

Единственная защита от дублей — поиск по external_id при создании заказа. На уровне базы данных никакой защиты нет — external_id намеренно не уникален (см. 10.3), поэтому это не строгая гарантия.

Что гарантируется: одновременные запросы на создание через этот API с одинаковым external_id обрабатываются по очереди — второй увидит заказ, созданный первым, и вернёт 200 с ним же, а не создаст дубликат. Это закрывает обычный случай повтора, отправленного пока первый запрос ещё обрабатывается.

Чего гарантия не покрывает: дубликаты, созданные другими путями (импорт из файла, веб-интерфейс, другой ключ), остаются возможны, и заказ с таким external_id может уже существовать в нескольких экземплярах. Тогда вернётся самый ранний из них.

Обязательное правило остаётся прежним: при таймауте или ошибке 5xx не повторяйте запрос вслепую. Сначала выполните GET /orders/?external_id=..., убедитесь, создался ли заказ, и только потом принимайте решение. Помните, что этот запрос может вернуть несколько заказов.