Error Response Format

All error responses follow this structure:

{
  "_links": {
    "about": { "href": "/api/v1/tenants/4444" }
  },
  "errorCode": "ResourceNotFound",
  "httpCode": 404,
  "localizedUserMessage": {
    "key": "generic_url_not_found",
    "renderedMessage": "Requested resource not found."
  }
}

Error Response Properties

Property Description
_links.about URI the failed request was issued against
httpCode HTTP status code (number)
errorCode Application-specific error code (more granular than HTTP code)
localizedUserMessage.key Unique key for custom error messages
localizedUserMessage.paramValues Substitutable parameters (conditional)
localizedUserMessage.renderedMessage Human-readable English message
developerMessage Debug hint from server runtime (when configured)
List<UserMessage> Detailed validation errors list

Error Codes

400 Bad Request

Error Code Description
InvalidSubscriberAccount User in X-Account-Authorization header cannot be mapped to valid user/location
InvalidRequest Syntax error parsing subscription accounts, tenant mismatch, invalid CallRequestType, or invalid scope parameter
RequestNotValidForSpecifiedDevice MakeCall with invalid deviceId, AnswerCall/resumeHeldCall with wrong device, holdCall/resumeCall/parkCall on SIP device
DataValidationError Request payload failed business logic validations
FrameworkBadRequest Client request is in invalid format
CallCancelled Call was cancelled before 3PCC operation could complete

401 Unauthorized

Error Code Description
BadAuthenticationHeader Missing Authorization header, unparseable credentials, blocked/disabled account, or invalid PIN

403 Forbidden

Error Code Description
FrameworkForbidden Authenticated user lacks sufficient application permission
RestrictedOperationAttempt MakeCall where authenticated user doesn't match originator
AccountNotCallParty Call not found for callObserverId, or user is not a party to the call

404 Not Found

Error Code Description
ResourceNotFound User mismatch with SubscriptionSet creator, unknown subscription set UUID, invalid WebSocket UUID, unparseable accountId, unknown request path, extension is not a user/location
RestrictedDataAccessAttempt Non-admin user trying to subscribe/access another user's data
FrameworkNotFound URL is completely invalid
FrameworkInvalidParam Path contains un-parseable URI variable
FrameworkInvalidPathParam Invalid path variable (e.g., incorrect tenantId)
FrameworkInvalidQueryParam Invalid query variable (e.g., incorrect siteTypeId)
InvalidParamValue Query parameter with invalid syntax (e.g., string for Boolean)
FeatureNotEnabled Querying a controlled-feature not enabled for the resource

405 Method Not Allowed

Error Code Description
FrameworkUnsupportedMethod Unsupported HTTP method for the resource

406 Not Acceptable

Error Code Description
FrameworkUnacceptable Unsupported content type in Accept header (only application/hal+json)

409 Conflict