Erros

Quando um pedido à API falha, o badges.ninja devolve uma resposta de erro em JSON com um código de estado HTTP apropriado.

Formato dos erros

Todos os erros seguem esta estrutura:

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

Códigos de estado

Código	Significado	Quando ocorre
400	Bad Request	Parâmetros em falta ou inválidos
402	Payment Required	Quota mensal de atribuições atingida ou funcionalidade exige um plano superior
403	Forbidden	Limite do plano atingido (por exemplo, limite de emissor ou distintivo)
404	Not Found	O recurso pedido 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 em falta

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

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

E-mail inválido

{ "error": "invalid email" }

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

URL inválido

{ "error": "invalid URL" }

Solução: Forneça um URL completo, incluindo o protocolo, por exemplo, https://example.com.

Nome demasiado curto

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

Solução: Use um nome mais comprido. Os nomes de emissor exigem pelo menos 3 caracteres. Os nomes de destinatário exigem pelo menos 5 caracteres.

Emissor não verificado

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

Solução: Verifique o emissor primeiro. Consulte o e-mail do emissor para obter a ligação de verificação, ou use o endpoint Verificar emissor.

Quota mensal de atribuições atingida

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

Solução: Já utilizou todas as atribuições incluídas no seu plano neste período (Free: 100/mês, Starter: 1000/mês, Pro: 10 000/mês). Aguarde a próxima reposição ou faça upgrade do plano. Consulte Planos e facturação.

Limite de plano atingido

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

Solução: Atingiu o limite do seu plano para emissores, distintivos ou chaves de API. Elimine 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 está disponível apenas no plano Pro. Faça upgrade para activar a verificação em cadeia.

Blockchain não suportada

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

Solução: De momento, apenas matchain é suportado como parâmetro de blockchain.

Recurso com dependências

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

Solução: Elimine todos os distintivos do emissor antes de eliminar o emissor. De forma análoga, elimine todas as atribuições de um distintivo antes de eliminar o distintivo.

Não autorizado

{ "error": "not authorized" }

Solução: Só pode modificar recursos que lhe pertencem. Certifique-se de que está a usar a chave de API correcta.

HTML no texto de partilha

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

Solução: O texto de partilha tem de ser texto simples. Remova quaisquer etiquetas HTML do parâmetro de texto.