Tratamento de erros

A API de saude da vitalera utiliza codigos de estado HTTP padrao e retorna respostas de erro estruturadas para o ajudar a diagnosticar e resolver problemas na sua integracao de monitorizacao remota de pacientes (RPM). Quer esteja a recolher sinais vitais de dispositivos medicos ou a gerir fluxos clinicos, o tratamento de erros consistente garante uma troca de dados fiavel.

Formato de resposta de erro

Todas as respostas de erro seguem uma estrutura JSON consistente:

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

Para erros de validacao, a resposta inclui detalhes ao nivel do campo:

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

Codigos de estado HTTP comuns

Erros de cliente (4xx)

Codigo	Significado	Descricao
400	Bad Request	O corpo do pedido esta malformado ou falta campos obrigatorios. Verifique a resposta para erros de validacao ao nivel do campo.
401	Unauthorized	A autenticacao falhou. O token JWT esta em falta, expirou ou e invalido.
403	Forbidden	O utilizador autenticado nao tem permissao para aceder a este recurso ou realizar esta acao.
404	Not Found	O recurso solicitado nao existe, ou o utilizador nao tem visibilidade sobre ele.
422	Unprocessable Entity	O pedido esta bem formado mas contem erros semanticos (por exemplo, transicao de estado invalida, violacao de regra de negocio).
429	Too Many Requests	Limite de taxa excedido. Consulte Limitacao de taxa para detalhes sobre limites e estrategias de retry.

Erros de servidor (5xx)

Codigo	Significado	Descricao
500	Internal Server Error	Ocorreu um erro inesperado no servidor. Se persistir, contacte o suporte com o ID do pedido.
502	Bad Gateway	Um servico a jusante esta temporariamente indisponivel. Tente novamente apos um breve atraso.
503	Service Unavailable	O servico esta em manutencao. Consulte a pagina de estado para atualizacoes.

Erros de autenticacao

Token expirado

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

Resolucao: Solicite um novo access token utilizando o seu refresh token ou client credentials. Consulte Autenticacao.

Token em falta

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

Resolucao: Inclua um token JWT valido no cabecalho Authorization: Bearer <token>.

Erros de validacao

Os erros de validacao retornam 400 Bad Request com mensagens especificas do campo:

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

Resolucao: Corrija os campos indicados e tente novamente o pedido. Consulte a Referencia API para valores de campo validos.

Erros de limitacao de taxa

Quando excede o limite de taxa, a API retorna 429 Too Many Requests:

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

Resolucao: Aguarde pela duracao indicada na resposta ou no cabecalho Retry-After antes de tentar novamente. Consulte Limitacao de taxa para detalhes de quotas.

Dicas de resolucao de problemas

1. Verifique o corpo da resposta -- as respostas de erro incluem sempre uma mensagem detail legivel por humanos.
2. Valide o seu JWT -- utilize jwt.io para descodificar o seu token e verificar a sua expiracao (claim exp).
3. Verifique as permissoes -- certifique-se de que a sua aplicacao ou funcao de utilizador tem acesso ao recurso solicitado.
4. Reveja o formato do pedido -- compare o seu pedido com os exemplos da Referencia API.
5. Verifique os limites de taxa -- se receber respostas 429, implemente backoff exponencial.
6. Contacte o suporte -- para erros 500 persistentes, contacte support@vitalera.io com o timestamp do pedido e o endpoint.