Ошибки

Любой неуспешный запрос возвращает конверт ошибки со стабильным code и сообщением message на английском:

{
  "success": false,
  "error": {
    "code": "field_not_found",
    "message": "Field not found."
  }
}

Принимайте решения по code и HTTP-статусу. Сообщения предназначены для людей и могут меняться. Некоторые ошибки содержат дополнительное поле внутри error, например existing_field_id.

Ошибки никогда не оплачиваются. Запросы изображений при ошибке возвращают этот JSON-конверт с Content-Type: application/json вместо картинки.

Коды ошибок

Статус	`code`	Значение	Что делать
202	`data_pending`	Данные готовятся. Это не ошибка; см. Готовность поля.	Подождать `Retry-After` секунд и повторить.
400	`invalid_request`	Параметр или тело запроса некорректны: не хватает поля, неверная дата, `limit` или `width` вне диапазона, неизвестный `format` или `source`, неверный `cursor`.	Исправить запрос.
400	`invalid_geometry`	Геометрия не является корректным `Polygon` или `MultiPolygon` в WGS84 или пересекает сама себя.	Исправить границу.
400	`field_too_large`	Поле больше лимита на одно поле по договору.	Разделить поле или попросить увеличить лимит.
400	`invalid_index`	Неизвестный индекс или индекс, который выбранный `source` не поддерживает.	Взять индекс из списка.
400	`invalid_date_range`	`to` раньше `from` или окно длиннее 366 дней.	Сократить окно.
400	`date_out_of_range`	Окно начинается раньше самой ранней даты, разрешённой договором. Дата указана в сообщении.	Начать окно позже.
401	`invalid_api_key`	Ключ не передан, неизвестен, отозван или истёк либо доступ к API для организации выключен.	Проверить ключ; см. Аутентификация.
403	`quota_exceeded`	Исчерпаны юниты за месяц или гектары по договору.	Дождаться следующего месяца или связаться с AgroSat.
403	`source_not_enabled`	`source=planet` без договора на Planet.	Использовать `sentinel-2` или связаться с AgroSat.
404	`field_not_found`	Среди полей API вашей организации нет поля с таким id. То же для удалённых полей.	Проверить id.
404	`no_imagery_for_date`	На эту дату нет снимка или его нельзя отрисовать.	Выбрать дату из дат снимков.
404	`not_found`	Нет такого эндпоинта или метод для него не поддерживается.	Проверить метод и путь.
409	`external_id_conflict`	`external_id` уже занят полем с другой геометрией. Его id — в `error.existing_field_id`.	Взять другой `external_id` или сначала удалить старое поле.
409	`duplicate_geometry`	Поле перекрывает уже зарегистрированное более чем на 80 % своей площади. Его id — в `error.existing_field_id`.	Использовать существующее поле.
429	`rate_limited`	Слишком много запросов с этим ключом за последнюю минуту или одновременно несколько регистраций в организации.	Подождать `Retry-After` секунд; см. Лимиты частоты.
500	`internal_error`	Непредвиденный сбой на нашей стороне.	Повторить с растущей задержкой. Если не проходит, сообщить в AgroSat время, эндпоинт и id поля.

Повторы

Ответ	Повторять?
`202`, `429`	Да, через `Retry-After` секунд.
`500` и сетевые ошибки	Да, с экспоненциальной задержкой. Регистрацию повторять безопасно; см. Регистрация полей.
Остальные `4xx`	Нет. Тот же запрос будет падать так же, пока вы его не измените или не изменится договор.

Что дальше

Справочник APIКакие ошибки возвращает каждый эндпоинт (на английском).

Готовность поляВсё о 202 data_pending.