Помилки

Коли API-запит завершується невдачею, badges.ninja повертає JSON з описом помилки та відповідним HTTP-статусом.

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

Усі помилки мають таку структуру:

{
  "error": "description of what went wrong"
}

Коди статусів

Код	Значення	Коли виникає
400	Bad Request	Відсутні чи неправильні параметри
402	Payment Required	Досягнута місячна квота нагород або функція потребує вищого тарифу
403	Forbidden	Досягнутий ліміт тарифу (наприклад, за емітентами чи значками)
404	Not Found	Запитаний ресурс не існує
429	Too Many Requests	Перевищено ліміт частоти
500	Internal Server Error	Непередбачена помилка на сервері

Типові помилки та рішення

Відсутні обовʼязкові параметри

{ "error": "missing required parameters: name, url, email" }

Рішення: Включіть усі обовʼязкові параметри в тіло запиту. Перевірте документацію ендпоінта.

Неправильний e-mail

{ "error": "invalid email" }

Рішення: Передайте коректну адресу у форматі user@domain.com.

Неправильний URL

{ "error": "invalid URL" }

Рішення: Передайте повний URL із протоколом, наприклад https://example.com.

Занадто коротке імʼя

{ "error": "name must be at least 3 characters" }

Рішення: Використайте довше імʼя. Для імені емітента потрібно мінімум 3 символи. Для імені одержувача — 5 символів.

Емітента не підтверджено

{ "error": "issuer must be verified before creating badges" }

Рішення: Спочатку підтвердіть емітента. Перевірте пошту емітента на посилання підтвердження або скористайтеся ендпоінтом Verify Issuer.

Досягнуто місячної квоти нагород

{ "error": "monthly award quota reached" }

Рішення: Ви використали всі нагороди за тарифом у поточному періоді (Free: 100/міс, Starter: 1 000/міс, Pro: 10 000/міс). Зачекайте наступного скидання або підвищте тариф. Див. Тарифи та оплата.

Досягнуто ліміту тарифу

{ "error": "issuer limit reached for your plan" }

Рішення: Ви вичерпали ліміт тарифу на емітентів, значки чи ключі API. Видаліть невикористаний ресурс або підвищте тариф.

Блокчейн потребує Pro

{ "error": "blockchain verification requires the Pro plan" }

Рішення: Параметр blockchain доступний лише на тарифі Pro. Перейдіть на нього для увімкнення on-chain-верифікації.

Непідтримуваний блокчейн

{ "error": "unsupported blockchain, only 'matchain' is supported" }

Рішення: Наразі як значення параметра підтримується лише matchain.

У ресурсу є залежності

{ "error": "issuer has badges and cannot be deleted" }

Рішення: Видаліть усі значки під емітентом, перш ніж видаляти емітента. Аналогічно, видаліть усі нагороди під значком, перш ніж видаляти значок.

Не авторизовано

{ "error": "not authorized" }

Рішення: Можна змінювати лише свої ресурси. Переконайтеся, що використовуєте правильний ключ API.

HTML у тексті шерингу

{ "error": "HTML tags are not allowed" }

Рішення: Текст шерингу має бути простим текстом. Видаліть HTML-теги з параметра text.