Erori

Când o cerere API eșuează, badges.ninja returnează un răspuns de eroare JSON cu un cod de stare HTTP adecvat.

Formatul erorii

Toate erorile urmează această structură:

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

Coduri de stare

Cod	Semnificație	Când apare
400	Cerere incorectă	Parametri lipsă sau nevalizi, limită de plan sau cotă atinsă, funcționalitatea necesită un plan superior sau lipsa autorizării — toate eșecurile de validare returnează 400
402	Plată necesară	Rezervat pentru epuizarea creditelor. API-ul badges nu deduce în prezent credite, deci acest cod nu este returnat în practică
404	Negăsit	Resursa solicitată nu există
500	Eroare internă a serverului	A apărut o eroare neașteptată pe server

Nu există 403 sau 429: erorile de autorizare returnează 400 („not authorized”), iar la nivel de aplicație nu există limitare a ratei de cereri.

Erori frecvente și soluții

Parametri obligatorii lipsă

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

Soluție: Include toți parametrii obligatorii în corpul cererii. Consultă documentația endpoint-ului pentru lista completă.

E-mail nevalid

{ "error": "invalid email" }

Soluție: Furnizează o adresă de e-mail validă, în formatul user@domain.com.

URL nevalid

{ "error": "invalid URL" }

Soluție: Furnizează un URL complet, inclusiv protocolul, de exemplu https://example.com.

Nume prea scurt

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

Soluție: Folosește un nume mai lung. Numele emitenților necesită cel puțin 3 caractere. Numele destinatarilor necesită cel puțin 5 caractere.

Emitent neverificat

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

Soluție: Verifică mai întâi emitentul. Caută linkul de verificare în e-mailul emitentului sau folosește endpoint-ul Verificare emitent.

Cota de credențiale atinsă (400)

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

Soluție: Ai folosit întregul pool anual de credențiale (Free: 1.200/an, Starter: 12.000/an, Pro: 120.000/an). Pool-ul se resetează la aniversarea înregistrării contului tău — nu la sfârșitul unei luni calendaristice. Treci la un plan superior pentru o limită mai mare. Consultă Planuri și facturare.

Limita planului atinsă (400)

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

Limita de insigne folosește aceeași formă:

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

Soluție: Ai atins limita planului pentru emitenți sau insigne. Șterge o resursă nefolosită sau treci la un plan superior.

Resursa are dependențe (400)

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

Soluție: Șterge toate insignele asociate emitentului înainte de a șterge emitentul. În mod similar, șterge toate credențialele aferente unei insigne înainte de a șterge insigna.

Neautorizat (400)

{ "error": "not authorized" }

Erorile de autorizare sunt erori de validare, deci returnează 400 (nu 401 sau 403).

Soluție: Poți modifica doar resursele pe care le deții. Asigură-te că folosești cheia API corectă.

HTML în textul de partajare

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

Soluție: Textul de partajare trebuie să fie text simplu. Elimină orice etichete HTML din parametrul text.