Errori

Quando una richiesta API fallisce, badges.ninja restituisce una risposta JSON di errore con il codice HTTP opportuno.

Formato dell'errore

Tutti gli errori seguono questa struttura:

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

Codici di stato

Codice	Significato	Quando accade
400	Bad Request	Parametri mancanti o non validi
402	Payment Required	Dotazione mensile di rilasci raggiunta o funzione che richiede un piano superiore
403	Forbidden	Limite di piano raggiunto (es. tetto di emittenti o credenziali)
404	Not Found	La risorsa richiesta non esiste
429	Too Many Requests	Limite di frequenza superato
500	Internal Server Error	Si è verificato un errore inatteso sul server

Errori ricorrenti 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.

E-mail non valida

{ "error": "invalid email" }

Soluzione: Fornisci un indirizzo e-mail valido nel formato user@domain.com.

URL non valido

{ "error": "invalid URL" }

Soluzione: Fornisci un URL completo che includa il protocollo, es. 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 la sua e-mail per il link di verifica oppure utilizza l'endpoint Verify Issuer.

Dotazione mensile raggiunta

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

Soluzione: Hai esaurito i rilasci inclusi nel tuo piano per questo ciclo (Free: 100/mese, Starter: 1.000/mese, Pro: 10.000/mese). Attendi il successivo azzeramento oppure aggiorna il piano. Consulta Piani e fatturazione.

Limite di piano raggiunto

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

Soluzione: Hai raggiunto il tetto di emittenti, credenziali o chiavi API del tuo piano. Elimina una risorsa inutilizzata oppure aggiorna il piano.

Blockchain richiede Pro

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

Soluzione: Il parametro blockchain è disponibile soltanto nel piano Pro. Aggiorna il piano per abilitare la verifica on-chain.

Blockchain non supportata

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

Soluzione: Al momento è supportato soltanto matchain come valore del parametro blockchain.

Risorsa con dipendenze

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

Soluzione: Elimina prima tutte le credenziali dell'emittente. Allo stesso modo, elimina prima tutti i rilasci di una credenziale prima di eliminarla.

Non autorizzato

{ "error": "not authorized" }

Soluzione: Puoi modificare soltanto risorse di tua proprietà. Assicurati di utilizzare 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 qualsiasi tag HTML dal parametro di testo.