Error Handling

The vitalera healthcare API uses standard HTTP status codes and returns structured error responses to help you diagnose and resolve issues in your remote patient monitoring (RPM) integration. Whether you are collecting vital signs from medical devices or managing clinical workflows, consistent error handling ensures reliable data exchange.

Error Response Format

All error responses follow a consistent JSON structure:

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

For validation errors, the response includes field-level details:

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

Common HTTP Status Codes

Client Errors (4xx)

Code	Meaning	Description
400	Bad Request	The request body is malformed or missing required fields. Check the response for field-level validation errors.
401	Unauthorized	Authentication failed. The JWT token is missing, expired, or invalid.
403	Forbidden	The authenticated user does not have permission to access this resource or perform this action.
404	Not Found	The requested resource does not exist, or the user does not have visibility to it.
422	Unprocessable Entity	The request is well-formed but contains semantic errors (e.g., invalid state transition, business rule violation).
429	Too Many Requests	Rate limit exceeded. See Rate Limiting for details on limits and retry strategies.

Server Errors (5xx)

Code	Meaning	Description
500	Internal Server Error	An unexpected error occurred on the server. If this persists, contact support with the request ID.
502	Bad Gateway	A downstream service is temporarily unavailable. Retry after a short delay.
503	Service Unavailable	The service is undergoing maintenance. Check the status page for updates.

Authentication Errors

Expired Token

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

Resolution: Request a new access token using your refresh token or client credentials. See Authentication.

Missing Token

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

Resolution: Include a valid JWT token in the Authorization: Bearer <token> header.

Validation Errors

Validation errors return 400 Bad Request with field-specific messages:

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

Resolution: Fix the indicated fields and retry the request. Refer to the API Reference for valid field values.

Rate Limiting Errors

When you exceed the rate limit, the API returns 429 Too Many Requests:

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

Resolution: Wait for the duration indicated in the response or the Retry-After header before retrying. See Rate Limiting for quota details.

Troubleshooting Tips

1. Check the response body -- error responses always include a human-readable detail message.
2. Validate your JWT -- use jwt.io to decode your token and check its expiration (exp claim).
3. Verify permissions -- ensure your application or user role has access to the requested resource.
4. Review request format -- compare your request against the API Reference examples.
5. Check rate limits -- if you receive 429 responses, implement exponential backoff.
6. Contact support -- for persistent 500 errors, contact support@vitalera.io with the request timestamp and endpoint.