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
402	Payment Required	Cota mensal de concessões atingida ou o recurso exige plano superior
403	Forbidden	Limite do plano atingido (ex.: teto de emissores ou distintivos)
404	Not Found	O recurso solicitado não existe
429	Too Many Requests	Limite de taxa excedido
500	Internal Server Error	Ocorreu um erro inesperado no servidor

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

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

Solução: Você usou todas as concessões incluídas no seu plano neste ciclo de faturamento (Free: 100/mês, Starter: 1.000/mês, Pro: 10.000/mês). Aguarde a próxima redefinição ou faça upgrade do plano. Veja Planos e faturamento.

Limite do plano atingido

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

Solução: Você atingiu o teto do seu plano para emissores, distintivos ou chaves de API. Exclua um recurso não utilizado ou faça upgrade do plano.

Blockchain exige Pro

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

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

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

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

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

Não autorizado

{ "error": "not authorized" }

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.