Erros

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

Formato de erro

Todos os erros seguem esta estrutura:

{
  "error": "descrição do que deu errado"
}

Códigos de status

Código	Significado	Quando acontece
400	Bad Request	Parâmetros ausentes ou inválidos, limite do plano ou cota atingida, recurso exige plano superior, ou não autorizado — todas as falhas de validação retornam 400
402	Payment Required	Reservado para esgotamento de créditos. A API de distintivos atualmente não desconta créditos, então este código nunca é retornado na prática
404	Not Found	O recurso solicitado não existe
500	Internal Server Error	Ocorreu um erro inesperado no servidor

Não há 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 a lista completa.

E-mail inválido

{ "error": "invalid email" }

Solução: Forneça um e-mail válido no formato user@domain.com.

URL inválida

{ "error": "invalid URL" }

Solução: Forneça uma URL completa incluindo o protocolo, ex.: https://example.com.

Nome muito curto

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

Solução: Use um nome mais longo. Nomes de emissor exigem ao menos 3 caracteres. Nomes de destinatário exigem ao menos 5.

Emissor não verificado

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

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

Cota mensal de concessões atingida (400)

{ "error": "monthly award quota reached (100/100 on the free plan) — wait for the 1st of next month or upgrade your plan" }

Solução: Você usou todas as concessões incluídas no seu plano no mês corrente do calendário (Free: 100/mês, Starter: 1.000/mês, Pro: 10.000/mês). O contador é redefinido às 00:00 UTC do dia 1º de cada mês; faça upgrade do plano para um limite maior. Veja Planos e faturamento.

Limite do plano atingido (400)

{ "error": "issuer limit reached (1/1 on the free plan) — delete an issuer or upgrade your plan" }

O teto de distintivos usa 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 teto do seu plano para emissores ou distintivos. Exclua um recurso não utilizado ou faça upgrade do plano.

Blockchain exige Pro (400)

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

Solução: O parâmetro blockchain só está disponível no plano Pro. Faça upgrade para habilitá-lo.

Blockchain não suportada

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

Solução: Atualmente só matchain é suportado como parâmetro de blockchain.

Recurso com dependências (400)

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

Solução: Exclua todos os distintivos vinculados ao emissor antes de excluir o emissor. Da mesma forma, exclua todas as concessões de um distintivo antes de excluí-lo.

Não autorizado (400)

{ "error": "not authorized" }

Falhas de autorização são erros de validação, portanto retornam 400 (não 401 nem 403).

Solução: Você só pode modificar recursos que são seus. 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 de texto.