Erori și convenții

Envelope JSON consistent; folosiți code și HTTP status pentru branching în client.

Succes (listă)

{
  "data": [ { } ],
  "meta": { "current_page": 1, "per_page": 25, "total": 100 },
  "links": { "next": "…", "prev": null }
}

Eroare

{
  "message": "Descriere scurtă pentru om",
  "code": "ERROR_CODE",
  "errors": {
    "field_name": ["Mesaj de validare"]
  }
}

HTTP	Situație tipică	Ce faceți
401	Token lipsă / invalid / revocat	Re-obțineți token
403	Fără acces la companie / modul / scope	Verificați X-Company-Id și modulele
404	Resursă inexistentă în context	Verificați id / cod / companie
422	Validare (câmpuri, UM întregi, status)	Citiți `errors`
429	Rate limit	Backoff + respectați antetele
503	Integrare neconfigurată (ex. eTSM token lipsă)	Configurați mediul / contactați suport

Rate limits

POST /api/auth/token: ~10 / minut
Endpoint-uri de date: ~60 / minut
Playground webhook test: limită separată pe server (throttle)

Health

GET /api/health (fără auth) returnează status agregat, checks, heartbeats, integrări și module. Util pentru monitoring; Prometheus: ?format=prometheus.

Schema completă: OpenAPI.