Skip to content

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 ​

StatusMeaningDescription
200OKThe request was successful.
201CreatedA new resource was successfully created.
204No ContentThe resource was successfully deleted.
400Bad RequestThe request was invalid — missing or invalid parameters, validation errors.
401UnauthorizedAuthentication failed or the access token is missing/invalid.
403ForbiddenThe API key does not have the required scopes for the requested endpoint.
404Not FoundThe requested resource does not exist.
405Method Not AllowedThe HTTP method is not supported for the requested endpoint.
409ConflictA resource with a unique field value already exists (e.g., duplicate name, email, NPI).
422Unprocessable EntityA referenced resource does not exist (e.g., invalid foreign key).
429Too Many RequestsThe client has sent too many requests in a given amount of time.
500Internal Server ErrorAn unexpected error occurred on the server.
503Service UnavailableThe 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 ​

FieldTypeAlways PresentDescription
codestringyesMachine-readable error code (see table below)
messagestringyesHuman-readable description of the error
fieldstringnoThe field that caused the error (e.g., on unique constraint violations)
requestIdstringnoAWS request ID for traceability
detailsanynoAdditional context (e.g., list of validation failures)

Error Codes ​

CodeHTTP StatusDescription
RESOURCE_EXISTS409A unique constraint was violated (duplicate name, email, NPI, etc.)
RESOURCE_NOT_FOUND404The requested resource does not exist
VALIDATION_ERROR400Request validation failed (missing or invalid fields)
INVALID_REFERENCE422A foreign key reference points to a non-existent resource
FORBIDDEN403The caller does not have permission for this action
RATE_LIMITED429Too many requests — try again later
INTERNAL_ERROR500An unexpected server error (details redacted in production)
SERVICE_UNAVAILABLE503Database 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.

Vivlio Health API Documentation