Errori

Quando una richiesta API non va a buon fine, badges.ninja restituisce una risposta di errore JSON con un codice di stato HTTP appropriato.

Formato degli errori

Tutti gli errori seguono questa struttura:

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

Codici di stato

Codice	Significato	Quando si verifica
400	Bad Request	Parametri mancanti o non validi, limite del piano o quota raggiunti, funzionalità che richiede un piano superiore oppure non autorizzato — tutti gli errori di validazione restituiscono 400
402	Payment Required	Riservato all'esaurimento dei crediti. L'API dei badge attualmente non scala crediti, quindi questo codice in pratica non viene mai restituito
404	Not Found	La risorsa richiesta non esiste
500	Internal Server Error	Si è verificato un errore imprevisto sul server

Non esistono 403 o 429: gli errori di autorizzazione restituiscono 400 ("not authorized") e non c'è alcun rate limiting a livello applicativo.

Errori comuni e soluzioni

Parametri obbligatori mancanti

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

Soluzione: includi tutti i parametri obbligatori nel corpo della richiesta. Consulta la documentazione dell'endpoint per l'elenco completo.

Email non valida

{ "error": "invalid email" }

Soluzione: fornisci un indirizzo email valido nel formato user@domain.com.

URL non valido

{ "error": "invalid URL" }

Soluzione: fornisci un URL completo che includa il protocollo, ad esempio https://example.com.

Nome troppo corto

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

Soluzione: usa un nome più lungo. I nomi degli emittenti richiedono almeno 3 caratteri. I nomi dei destinatari richiedono almeno 5 caratteri.

Emittente non verificato

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

Soluzione: verifica prima l'emittente. Controlla l'email dell'emittente per trovare il link di verifica, oppure usa l'endpoint Verifica emittente.

Quota di credenziali raggiunta (400)

{ "error": "Your Free plan reached its credential limit (1200/1200) — your allowance renews on your plan anniversary, or upgrade to Starter" }

Soluzione: hai esaurito l'intero pool annuale di credenziali (Free: 1.200/anno, Starter: 12.000/anno, Pro: 120.000/anno). Il pool si azzera nell'anniversario di registrazione del tuo account — non al cambio del mese di calendario. Passa a un piano superiore per ottenere un limite più alto. Vedi Piani e fatturazione.

Limite del piano raggiunto (400)

{ "error": "Your Free plan reached its issuer limit (2/2) — delete an issuer or upgrade to Starter" }

Il limite dei badge ha la stessa forma:

{ "error": "badge limit reached (5/5 on the starter plan) — delete a badge or upgrade your plan" }

Soluzione: hai raggiunto il limite del tuo piano per emittenti o badge. Elimina una risorsa inutilizzata oppure passa a un piano superiore.

La risorsa ha delle dipendenze (400)

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

Soluzione: elimina tutti i badge collegati all'emittente prima di eliminare l'emittente. Allo stesso modo, elimina tutte le credenziali di un badge prima di eliminare il badge.

Non autorizzato (400)

{ "error": "not authorized" }

Gli errori di autorizzazione sono errori di validazione, quindi restituiscono 400 (non 401 né 403).

Soluzione: puoi modificare solo le risorse di tua proprietà. Assicurati di usare la chiave API corretta.

HTML nel testo di condivisione

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

Soluzione: il testo di condivisione deve essere testo semplice. Rimuovi eventuali tag HTML dal parametro text.