Ошибки

Ошибка всегда приходит в формате RFC 9457 с типом application/problem+json:

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://docs.grem.capital/api/errors/business_rule",
  "title": "business_rule",
  "status": 422,
  "detail": "Describe the property: pick a listing or fill in at least a description, city or area",
  "code": "not_enough_input",
  "requestId": "req_..."
}

Пример ошибки проверки с полями:

{
  "title": "validation",
  "status": 400,
  "detail": "\"avatarId\" is required",
  "errors": [{ "field": "avatarId", "message": "\"avatarId\" is required" }],
  "requestId": "req_..."
}

Коды ошибок

Адрес из поля type ведет к соответствующему пункту этого списка.

invalid_key

401. Ключ не передан, неверен, отозван или истек. Проверьте заголовок Authorization и статус ключа в кабинете.

forbidden_scope

403. Ключ действителен, но не имеет нужной области доступа. Выдайте ключу область или создайте новый (Аутентификация).

forbidden

403. Действие не разрешено для этого аккаунта или ресурса: например, объект принадлежит другому аккаунту или роль в агентстве недостаточна. Причина - в detail.

insufficient_funds

402. Недостаточно средств в кошельке, исчерпана квота плана, есть неоплаченный долг или достигнут лимит добросовестного использования. Причина - в code: INSUFFICIENT_FUNDS, QUOTA_EXCEEDED, DEBT_OUTSTANDING, FAIR_USE_LIMIT_REACHED и т. п. Пополните баланс, погасите долг или смените тариф.

validation

400. Запрос не прошел проверку. Что именно не так - в detail и errors. Исправьте запрос; повторять без изменений бесполезно.

business_rule

422. Запрос составлен верно, но выполнить его нельзя: не хватает данных, объект в неподходящем состоянии, такой тип недвижимости не поддерживается и т. п. Причина - в detail, машинный код - в code.

payload_too_large

413. Тело запроса или файл больше лимита. Ограничения размера указаны в описании инструмента. Тело, которое не является корректным JSON, - 400 validation.

range_not_satisfiable

416. Range скачивания файла выходит за пределы файла. Размер файла - в Content-Range: bytes */size.

rate_limited

429. Превышен лимит частоты. Подождите столько секунд, сколько в заголовке Retry-After, и повторите (Лимиты и оплата). code говорит, какой лимит: minute_limit (секунды) или daily_limit (обновляется в 00:00 UTC).

not_found

404. Несуществующий путь или ресурс, которого нет или который вам не принадлежит. Чужой ресурс намеренно дает тот же ответ, что и несуществующий.

idempotency_conflict

409. Запрос с таким Idempotency-Key еще выполняется. Дождитесь завершения и повторите с тем же ключом (Идемпотентность). После таймаута (502 provider_error) ключ удерживается 15 минут: проверьте результат, прежде чем повторять, - повтор после удержания выполнит платную работу еще раз. Экспресс-оценка после таймаута ключ освобождает: повторите ее с тем же ключом. Тот же 409 приходит, когда оплата вызова с этим ключом еще резервируется (code RESERVE_IN_PROGRESS, RESERVE_BUSY) - повторите позже; RESERVE_REF_TAKEN - ключ исчерпан, отправьте новый.

conflict

409. Ресурс в состоянии, которое не позволяет это действие (например, перенос объекта из одного агентства в другое, удаление объекта с действующим договором о комиссии). Причина - в detail. Не повторяйте запрос без изменений.

service_unavailable

503. Инструмент временно недоступен. Ничего не списано. Повторите после паузы из Retry-After; текущее состояние инструментов показывает GET /tools/status.

provider_error

502. Сбой в сервисе, выполняющем работу. Временный: повторите с растущей паузой. Если detail сообщает, что инструмент не ответил вовремя, работа может ещё завершиться и быть оплаченной: проверьте GET /works, прежде чем запускать её снова; экспресс-оценку повторяйте с тем же Idempotency-Key. Результаты улучшения фото, сайта и черновика в GET /works не хранятся: для них дождитесь конца 15-минутного удержания и проверьте результат в кабинете или среди своих объектов.

internal_error

500. Внутренняя ошибка. Повторите с паузой; если повторяется, напишите в поддержку и укажите requestId.

Список кодов может расширяться. Неизвестный код обрабатывайте как общую ошибку своего HTTP-класса (4xx - ошибка запроса, 5xx - сбой сервиса).

Что повторять

Повторяя создающие запросы, всегда передавайте тот же Idempotency-Key - тогда повтор не выполнит и не спишет работу второй раз.

Исключения

• События Swipe Match (POST /match/leads/{id}/events), которые не разрешены текущим состоянием лида, отвечают 409 с title: business_rule и кодом в code (client_event_rejected, invalid_transition, not_available).
• Действия с пулом лидов агентства (POST /leads/{id}/claim, POST /leads/{id}/return-to-pool) личным ключом или без нужной роли отвечают 403 с title: forbidden.

Что не тарифицируется

Отклоненный запрос (любой ответ 4xx или 5xx) не списывает вызов API. Цена инструмента списывается только за принятую работу. Исключение - provider_error после таймаута: работа может завершиться и быть оплачена - проверьте GET /works, прежде чем запускать ее снова (улучшение фото, сайт и черновик - в кабинете или среди своих объектов).

Связанные статьи

• Лимиты и оплата
• Идемпотентность
• Аутентификация