Помилки

Помилка завжди приходить у форматі 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, перш ніж запускати її знову (покращення фото, сайт і чернетка - у кабінеті або серед своїх об'єктів).

Пов'язані статті

• Ліміти і оплата
• Ідемпотентність
• Автентифікація