Error Handling
The Vivlio Health API uses standard HTTP status codes and structured error responses to indicate the success or failure of an API request.
HTTP Status Codes
| Status | Meaning | Description |
|---|---|---|
| 200 | OK | The request was successful. |
| 201 | Created | A new resource was successfully created. |
| 204 | No Content | The resource was successfully deleted. |
| 400 | Bad Request | The request was invalid — missing or invalid parameters, validation errors. |
| 401 | Unauthorized | Authentication failed or the access token is missing/invalid. |
| 403 | Forbidden | The API key does not have the required scopes for the requested endpoint. |
| 404 | Not Found | The requested resource does not exist. |
| 405 | Method Not Allowed | The HTTP method is not supported for the requested endpoint. |
| 409 | Conflict | A resource with a unique field value already exists (e.g., duplicate name, email, NPI). |
| 422 | Unprocessable Entity | A referenced resource does not exist (e.g., invalid foreign key). |
| 429 | Too Many Requests | The client has sent too many requests in a given amount of time. |
| 500 | Internal Server Error | An unexpected error occurred on the server. |
| 503 | Service Unavailable | The database or a downstream service is temporarily unavailable. |
Structured Error Response
All error responses return a JSON body with a structured error object:
json
{
"error": {
"code": "RESOURCE_EXISTS",
"message": "A resource with that name already exists",
"field": "name",
"requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}Error Object Fields
| Field | Type | Always Present | Description |
|---|---|---|---|
code | string | yes | Machine-readable error code (see table below) |
message | string | yes | Human-readable description of the error |
field | string | no | The field that caused the error (e.g., on unique constraint violations) |
requestId | string | no | AWS request ID for traceability |
details | any | no | Additional context (e.g., list of validation failures) |
Error Codes
| Code | HTTP Status | Description |
|---|---|---|
RESOURCE_EXISTS | 409 | A unique constraint was violated (duplicate name, email, NPI, etc.) |
RESOURCE_NOT_FOUND | 404 | The requested resource does not exist |
VALIDATION_ERROR | 400 | Request validation failed (missing or invalid fields) |
INVALID_REFERENCE | 422 | A foreign key reference points to a non-existent resource |
FORBIDDEN | 403 | The caller does not have permission for this action |
RATE_LIMITED | 429 | Too many requests — try again later |
INTERNAL_ERROR | 500 | An unexpected server error (details redacted in production) |
SERVICE_UNAVAILABLE | 503 | Database or downstream service temporarily unreachable |
Error Response Examples
409 Conflict — duplicate resource
json
{
"error": {
"code": "RESOURCE_EXISTS",
"message": "A resource with that username already exists",
"field": "username",
"requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}422 Unprocessable Entity — invalid reference
json
{
"error": {
"code": "INVALID_REFERENCE",
"message": "Referenced resource does not exist",
"requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}400 Bad Request — validation failure
json
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation failed on: firstName, email",
"requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}503 Service Unavailable — database connection error
json
{
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "Database temporarily unavailable",
"requestId": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
}Request Tracing
Always capture the requestId from error responses. Include it when reporting issues to support for faster troubleshooting.
