Erori

Coduri de status

Cod	Semnificație
400	Cerere invalidă la nivel de protocol. Rezervat — API-ul curent nu emite explicit acest cod; un body JSON malformat este tratat ca lipsă și cade pe validarea câmpurilor (422).
401	Autentificare eșuată — cheie lipsă, format greșit, tenant necunoscut sau cheie invalidă. Vezi autentificare.
403	Autentificat, dar fără autorizație — cheie inactivă/expirată, IP nepermis, cont suspendat sau capabilitate lipsă.
404	Resursa nu există (sau nu aparține tenantului tău, ceea ce arată la fel).
409	Conflict — de exemplu o companie cu același tax_id există deja.
422	Validarea a eșuat, sau ștergerea este blocată de înregistrări asociate.
429	Limita de rată depășită. Vezi limite de rată.
500	Eroare de server neașteptată — nu are un body specific API-ului; reîncearcă și, dacă persistă, contactează suportul.

Forma body-ului de eroare

Majoritatea erorilor API-ului au forma simplă:

{ "error": "Descriere lizibilă a problemei." }

Exemple reale, luate direct din implementare:

Situație	Cod	Body
Antet Authorization lipsă	401	{"error": "API key missing. Use Authorization: Bearer <tenant>.<key>"}
Token fără prefixul de tenant	401	{"error": "Invalid API key format. Expected: <tenant>.<key>"}
Tenant necunoscut	401	{"error": "Invalid API key (unknown tenant)."}
Cheie inexistentă	401	{"error": "Invalid API key."}
Cheie inactivă sau expirată	403	{"error": "API key is inactive or expired."}
Tenant suspendat	403	{"error": "Account suspended."}
IP nepermis pentru această cheie	403	{"error": "IP address not allowed."}
Capabilitate lipsă	403	{"error": "Missing capability: companies:write"}
Limită de rată depășită	429	{"error": "Rate limit exceeded."}

Validare (422)

Cererile de creare/actualizare care eșuează validarea returnează câmpul error fix și un obiect errors cu mesajele per câmp (forma standard a validatorului Laravel, nu textul implicit message):

{
    "error": "Validation failed.",
    "errors": {
        "name": ["The name field is required."]
    }
}

Ștergere blocată (422)

Ștergerea unei companii cu înregistrări asociate (facturi, oferte, tranzacții, tichete sau abonamente) este refuzată, nu forțată:

{
    "error": "Cannot delete company with related records.",
    "details": "Blocked by: invoices, tickets."
}

Conflict (409)

Un POST /api/v1/companies cu un tax_id deja existent nu creează un duplicat — returnează 409 cu datele companiei existente, astfel încât un apelant care reîncearcă poate recupera fără o a doua cerere:

{
    "error": "Company with this tax_id already exists.",
    "data": {
        "id": 42,
        "name": "Wartung SRL",
        "tax_id": "RO12345678"
    }
}

Resursă inexistentă (404)

O resursă inexistentă (de exemplu GET /api/v1/companies/99999) produce un 404 din stratul standard Laravel de rutare — forma body-ului diferă de restul API-ului (message, nu error):

{ "message": "No query results for model [App\\Models\\Company] 99999" }