Erros

Quando uma requisição à API falha, o badges.ninja retorna uma resposta de erro em JSON com um código de status HTTP apropriado.

Formato do erro

Todos os erros seguem esta estrutura:

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

Códigos de status

Código	Significado	Quando ocorre
400	Requisição inválida	Parâmetros ausentes ou inválidos, limite do plano ou cota atingido, recurso que exige um plano superior ou falta de autorização — todas as falhas de validação retornam 400
402	Pagamento necessário	Reservado para o esgotamento de créditos. A API do badges atualmente não deduz créditos, portanto este código nunca é retornado na prática
404	Não encontrado	O recurso solicitado não existe
500	Erro interno do servidor	Ocorreu um erro inesperado no servidor

Não existem os códigos 403 nem 429: falhas de autorização retornam 400 ("not authorized") e não há limitação de taxa na camada da aplicação.

Erros comuns e soluções

Parâmetros obrigatórios ausentes

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

Solução: Inclua todos os parâmetros obrigatórios no corpo da requisição. Consulte a documentação do endpoint para ver a lista completa.

E-mail inválido

{ "error": "invalid email" }

Solução: Informe um endereço de e-mail válido no formato user@domain.com.

URL inválida

{ "error": "invalid URL" }

Solução: Informe uma URL completa, incluindo o protocolo, por exemplo https://example.com.

Nome muito curto

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

Solução: Use um nome mais longo. Os nomes de emissores exigem pelo menos 3 caracteres. Os nomes de destinatários exigem pelo menos 5 caracteres.

Emissor não verificado

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

Solução: Verifique o emissor primeiro. Procure o link de verificação no e-mail do emissor ou use o endpoint Verificar emissor.

Cota de credenciais atingida (400)

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

Solução: Você usou todo o seu conjunto anual de credenciais (Free: 1.200/ano, Starter: 12.000/ano, Pro: 120.000/ano). O conjunto é reiniciado no aniversário de registro da sua conta — não na virada do mês do calendário. Faça upgrade do plano para obter uma cota maior. Veja Planos e cobrança.

Limite do plano atingido (400)

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

O limite de emblemas segue o mesmo formato:

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

Solução: Você atingiu o limite de emissores ou emblemas do seu plano. Exclua um recurso não utilizado ou faça upgrade do plano.

Recurso com dependências (400)

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

Solução: Exclua todos os emblemas vinculados ao emissor antes de excluí-lo. Da mesma forma, exclua todas as credenciais de um emblema antes de excluir o emblema.

Não autorizado (400)

{ "error": "not authorized" }

Falhas de autorização são erros de validação, por isso retornam 400 (e não 401 ou 403).

Solução: Você só pode modificar recursos que lhe pertencem. Verifique se está usando a chave de API correta.

HTML no texto de compartilhamento

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

Solução: O texto de compartilhamento deve ser texto simples. Remova quaisquer tags HTML do parâmetro text.