Erros

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

Formato do erro

Todos os erros seguem esta estrutura:

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

Códigos de estado

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

Não existem os códigos 403 nem 429: as falhas de autorização devolvem 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 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 ver a lista completa.

E-mail inválido

{ "error": "invalid email" }

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

URL inválido

{ "error": "invalid URL" }

Solução: Indique 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 longo. Os nomes de emissores exigem pelo menos 3 carateres. Os nomes de destinatários exigem pelo menos 5 carateres.

Emissor não verificado

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

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

Quota 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: Utilizou todo o seu conjunto anual de credenciais (Free: 1200/ano, Starter: 12 000/ano, Pro: 120 000/ano). O conjunto é reposto no aniversário de registo da sua conta — não na viragem do mês civil. Atualize o seu plano para obter uma quota maior. Consulte Planos e faturação.

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: Atingiu o limite de emissores ou emblemas do seu plano. Elimine um recurso não utilizado ou atualize o plano.

Recurso com dependências (400)

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

Solução: Elimine todos os emblemas associados ao emissor antes de o eliminar. Da mesma forma, elimine todas as credenciais de um emblema antes de eliminar o emblema.

Não autorizado (400)

{ "error": "not authorized" }

As falhas de autorização são erros de validação, por isso devolvem 400 (e não 401 nem 403).

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

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 text.