Початок роботи

Помилки

Формат помилок, коди статусів і коли варто повторювати запит.

Помилки використовують звичайні коди статусів HTTP і завжди повертають однакову JSON-обгортку зі стабільним машинним кодом.

Формат помилки#

{
  "error": {
    "code": "rateLimited",
    "message": "Rate limit exceeded",
    "retryAfter": 12
  }
}

error.code стабільний, на нього можна спиратися в коді. error.message — підказка для людини, вона може змінюватися. Деякі помилки додають поля: retryAfter для лімітів, reason для квот і обмежень тарифу, issues для помилок валідації.

Коди помилок#

Статус	Код	Значення	Повторювати?
400	validation	Некоректний параметр або тіло запиту; дивись `error.issues`.	Ні
401	unauthorized	API-ключ відсутній, некоректний або відкликаний.	Ні
402	planRequired	Тариф не включає доступ до API або цю функцію.	Ні
403	forbidden	Запит заборонений.	Ні
404	notFound	Токен ще не сканували або гаманець ще не профілювали.	Пізніше
409	conflict	Запит конфліктує з поточним станом.	Ні
429	rateLimited	Забагато запитів на хвилину або вичерпано місячну квоту.	Так
500	generic	Збій на нашому боці.	Так
503	unavailable	Техобслуговування або в постачальника даних закінчилася потужність.	Пізніше

Помилки валідації#

Некоректні параметри повертають 400 зі списком issues, що вказують на проблемне поле.

400

{
  "error": {
    "code": "validation",
    "message": "Invalid input",
    "issues": [
      {
        "path": "pageSize",
        "message": "Invalid input"
      }
    ]
  }
}