Gestió d'errors

L'API sanitària de vitalera utilitza codis d'estat HTTP estàndard i retorna respostes d'error estructurades per ajudar-vos a diagnosticar i resoldre problemes a la vostra integració de monitorització remota de pacients (RPM). Tant si esteu recollint constants vitals de dispositius mèdics com gestionant fluxos clínics, una gestió coherent d'errors assegura un intercanvi de dades fiable.

Format de resposta d'error

Totes les respostes d'error segueixen una estructura JSON consistent:

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

Per a errors de validació, la resposta inclou detalls a nivell de camp:

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

Codis d'estat HTTP comuns

Errors del client (4xx)

Codi	Significat	Descripció
400	Bad Request	El cos de la petició està mal format o falten camps obligatoris. Comproveu la resposta per a errors de validació de camps.
401	Unauthorized	L'autenticació ha fallat. El token JWT falta, ha caducat o no és vàlid.
403	Forbidden	L'usuari autenticat no té permís per accedir a aquest recurs o realitzar aquesta acció.
404	Not Found	El recurs sol·licitat no existeix, o l'usuari no té visibilitat sobre ell.
422	Unprocessable Entity	La petició està ben formada però conté errors semàntics (p. ex., transició d'estat no vàlida, violació de regla de negoci).
429	Too Many Requests	Límit de taxa superat. Consulteu Límits de taxa per a detalls sobre límits i estratègies de reintent.

Errors del servidor (5xx)

Codi	Significat	Descripció
500	Internal Server Error	S'ha produït un error inesperat al servidor. Si persisteix, contacteu amb suport amb l'ID de la petició.
502	Bad Gateway	Un servei posterior no està disponible temporalment. Torneu-ho a intentar després d'un breu retard.
503	Service Unavailable	El servei està en manteniment. Consulteu la pàgina d'estat per a actualitzacions.

Errors d'autenticació

Token caducat

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

Resolució: Sol·liciteu un nou token d'accés utilitzant el vostre token de renovació o les credencials de client. Consulteu Autenticació.

Token absent

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

Resolució: Incloeu un token JWT vàlid a la capçalera Authorization: Bearer <token>.

Errors de validació

Els errors de validació retornen 400 Bad Request amb missatges específics per camp:

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

Resolució: Corregiu els camps indicats i torneu a intentar la petició. Consulteu la Referència de l'API per als valors de camp vàlids.

Errors de limitació de taxa

Quan supereu el límit de taxa, l'API retorna 429 Too Many Requests:

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

Resolució: Espereu la durada indicada a la resposta o la capçalera Retry-After abans de tornar a intentar. Consulteu Límits de taxa per a detalls de quotes.

Consells de resolució de problemes

1. Comproveu el cos de la resposta -- les respostes d'error sempre inclouen un missatge detail llegible per humans.
2. Valideu el vostre JWT -- utilitzeu jwt.io per descodificar el vostre token i comprovar la seva caducitat (afirmació exp).
3. Verifiqueu els permisos -- assegureu-vos que la vostra aplicació o rol d'usuari té accés al recurs sol·licitat.
4. Reviseu el format de la petició -- compareu la vostra petició amb els exemples de la Referència de l'API.
5. Comproveu els límits de taxa -- si rebeu respostes 429, implementeu reintent exponencial.
6. Contacteu amb suport -- per a errors 500 persistents, contacteu amb support@vitalera.io amb la marca de temps de la petició i el punt d'accés.