Ошибки

Если запрос к API завершается неудачей, badges.ninja возвращает JSON-ответ с ошибкой и соответствующим HTTP-кодом состояния.

Формат ошибки

Все ошибки имеют следующую структуру:

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

Коды состояния

Код	Значение	Когда возникает
400	Неверный запрос	Отсутствуют или недопустимы параметры, достигнут лимит плана или квота, функция требует более высокого плана, либо нет авторизации — все ошибки валидации возвращают 400
402	Требуется оплата	Зарезервирован для исчерпания кредитов. API badges в настоящее время не списывает кредиты, поэтому на практике этот код не возвращается
404	Не найдено	Запрошенный ресурс не существует
500	Внутренняя ошибка сервера	На сервере произошла непредвиденная ошибка

Кодов 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.