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, limite do plano ou quota atingida, funcionalidade exige um plano superior, ou não autorizado — todas as falhas de validação devolvem 400
402	Payment Required	Reservado para esgotamento de créditos. A API de distintivos não deduz créditos actualmente, pelo que este código nunca é devolvido na prática
404	Not Found	O recurso pedido não existe
500	Internal Server Error	Ocorreu um erro inesperado no servidor

Não existe 403 nem 429: as falhas de autorização devolvem 400 ("not authorized") e não há limitação de taxa na camada de aplicação.

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 (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: Já utilizou todas as atribuições incluídas no seu plano para o mês de calendário actual (Free: 100/mês, Starter: 1000/mês, Pro: 10 000/mês). O contador é reposto às 00:00 UTC do dia 1 de cada mês; faça upgrade do plano para uma quota superior. Consulte Planos e facturação.

Limite de plano atingido (400)

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

O limite 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: Atingiu o limite do seu plano para emissores ou distintivos. Elimine 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 está disponível apenas no plano Pro. Faça upgrade para o activar.

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 (400)

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

Solução: Elimine todos os distintivos associados ao 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 (400)

{ "error": "not authorized" }

As falhas de autorização são erros de validação, pelo que devolvem 400 (e não 401 ou 403).

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.