Gestionarea erorilor

API-ul de sanatate vitalera utilizeaza coduri de stare HTTP standard si returneaza raspunsuri de eroare structurate pentru a va ajuta sa diagnosticati si sa rezolvati problemele din integrarea dumneavoastra de monitorizare la distanta a pacientilor (RPM). Fie ca colectati semne vitale de la dispozitive medicale sau gestionati fluxuri clinice, gestionarea consistenta a erorilor asigura un schimb de date fiabil.

Format de raspuns la erori

Toate raspunsurile de eroare urmeaza o structura JSON consistenta:

{
  "detail": "A human-readable description of the error.",
  "code": "error_code"
}

Pentru erori de validare, raspunsul include detalii la nivel de camp:

{
  "field_name": ["This field is required."],
  "nested_field": {
    "sub_field": ["Ensure this value is greater than 0."]
  }
}

Coduri de stare HTTP comune

Erori de client (4xx)

Cod	Semnificatie	Descriere
400	Bad Request	Corpul cererii este malformat sau lipsesc campurile obligatorii. Verificati raspunsul pentru erori de validare la nivel de camp.
401	Unauthorized	Autentificarea a esuat. Token-ul JWT lipseste, a expirat sau este invalid.
403	Forbidden	Utilizatorul autentificat nu are permisiunea sa acceseze aceasta resursa sau sa efectueze aceasta actiune.
404	Not Found	Resursa solicitata nu exista sau utilizatorul nu are vizibilitate asupra ei.
422	Unprocessable Entity	Cererea este bine formata, dar contine erori semantice (de exemplu, tranzitie de stare invalida, incalcarea regulilor de afaceri).
429	Too Many Requests	Limita de rata depasita. Consultati Limitarea ratei pentru detalii despre limite si strategii de reincercare.

Erori de server (5xx)

Cod	Semnificatie	Descriere
500	Internal Server Error	A aparut o eroare neasteptata pe server. Daca persista, contactati suportul cu ID-ul cererii.
502	Bad Gateway	Un serviciu downstream este temporar indisponibil. Reincercati dupa o scurta intarziere.
503	Service Unavailable	Serviciul se afla in mentenanta. Verificati pagina de stare pentru actualizari.

Erori de autentificare

Token expirat

{
  "detail": "Given token not valid for any token type",
  "code": "token_not_valid"
}

Rezolvare: Solicitati un nou token de acces utilizand refresh token-ul sau client credentials. Consultati Autentificare.

Token lipsa

{
  "detail": "Authentication credentials were not provided."
}

Rezolvare: Includeti un token JWT valid in header-ul Authorization: Bearer <token>.

Erori de validare

Erorile de validare returneaza 400 Bad Request cu mesaje specifice campului:

{
  "status": ["\"invalid\" is not a valid choice."],
  "effective_period_start": ["This field is required."]
}

Rezolvare: Corectati campurile indicate si reincercati cererea. Consultati Referinta API pentru valori valide ale campurilor.

Erori de limitare a ratei

Cand depasiti limita de rata, API-ul returneaza 429 Too Many Requests:

{
  "detail": "Request was throttled. Expected available in 30 seconds."
}

Rezolvare: Asteptati durata indicata in raspuns sau in header-ul Retry-After inainte de a reincerca. Consultati Limitarea ratei pentru detalii despre cote.

Sfaturi de depanare

1. Verificati corpul raspunsului -- raspunsurile de eroare includ intotdeauna un mesaj detail lizibil de catre om.
2. Validati JWT-ul dumneavoastra -- utilizati jwt.io pentru a decoda token-ul si a verifica expirarea acestuia (claim exp).
3. Verificati permisiunile -- asigurati-va ca aplicatia sau rolul de utilizator are acces la resursa solicitata.
4. Revizuiti formatul cererii -- comparati cererea cu exemplele din Referinta API.
5. Verificati limitele de rata -- daca primiti raspunsuri 429, implementati backoff exponential.
6. Contactati suportul -- pentru erori 500 persistente, contactati support@vitalera.io cu timestamp-ul cererii si endpoint-ul.