Помилки

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

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

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

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

Коди стану

Код	Значення	Коли виникає
400	Bad Request	Відсутні або недійсні параметри, досягнуто ліміт плану чи квоту, функція потребує вищого плану або немає авторизації — усі помилки валідації повертають 400
402	Payment Required	Зарезервовано для вичерпання кредитів. API badges наразі не списує кредити, тому цей код на практиці ніколи не повертається
404	Not Found	Запитаний ресурс не існує
500	Internal Server Error	На сервері сталася неочікувана помилка

Кодів 403 і 429 немає: збої авторизації повертають 400 («not authorized»), а обмеження частоти запитів на рівні застосунку відсутнє.

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

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

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

Рішення: Додайте всі обов’язкові параметри до тіла запиту. Повний перелік дивіться в документації відповідної кінцевої точки.

Недійсна електронна адреса

{ "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" }

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

Досягнуто квоту сертифікатів (400)

{ "error": "Your Free plan reached its credential limit (1200/1200) — your allowance renews on your plan anniversary, or upgrade to Starter" }

Рішення: Ви використали весь річний пул сертифікатів (Free: 1 200/рік, Starter: 12 000/рік, Pro: 120 000/рік). Пул скидається в річницю реєстрації вашого облікового запису, а не на межі календарного місяця. Перейдіть на вищий план, щоб отримати більший ліміт. Див. Плани та оплата.

Досягнуто ліміт плану (400)

{ "error": "Your Free plan reached its issuer limit (2/2) — delete an issuer or upgrade to Starter" }

Ліміт значків має таку саму форму:

{ "error": "badge limit reached (5/5 on the starter plan) — delete a badge or upgrade your plan" }

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

Ресурс має залежності (400)

{ "error": "issuer has 3 badge(s) linked — delete the badges first" }

Рішення: Перш ніж видаляти емітента, видаліть усі значки, пов’язані з ним. Так само перед видаленням значка видаліть усі сертифікати, видані за цим значком.

Немає авторизації (400)

{ "error": "not authorized" }

Збої авторизації є помилками валідації, тому повертають 400 (а не 401 чи 403).

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

HTML у тексті для поширення

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

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