Errors

The OLIFY API uses HTTP status codes to indicate success or failure. Most application errors return a JSON body with this envelope:

{
  "error": "ValidationException",
  "data": {
    "Message": "Code is required."
  },
  "traceId": "0HN…"
}

Field	Description
`error`	The error type. Use this value to classify the failure
`data`	Additional error-specific details. The object and its fields vary by error type and may be omitted
`traceId`	The request trace identifier. Include it when contacting OLIFY about a server error

Status codes

HTTP status	Error	Meaning
`400 Bad Request`	`ValidationException`	The request payload or a business rule failed validation. Inspect `data` for details
`401 Unauthorized`	No OLIFY API error envelope	The Bearer token is missing, expired, or invalid
`403 Forbidden`	`AuthorizationException`	The authenticated service account is not authorized for the operation or selected tenant. `data.isAuthenticated` is set
`404 Not Found`	`EntityNotFoundException`	The requested entity does not exist or is not visible in the selected tenant
`500 Internal Server Error`	`Exception`	The server could not complete the request

Validation errors

A malformed payload or failed business rule returns HTTP 400:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "ValidationException",
  "data": {
    "Message": "Code is required."
  },
  "traceId": "0HN…"
}

Read the fields in data and correct the request before retrying. Repeating an unchanged invalid request will produce the same failure.

A missing, expired, or invalid Bearer token returns HTTP 401. Authentication middleware produces this response before OLIFY API error handling, so it does not return the { "error", "data", "traceId" } envelope.

Obtain a valid access token and retry with:

Authorization: Bearer {access_token}

Authorization errors

An authenticated request that lacks access returns HTTP 403:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "AuthorizationException",
  "data": {
    "isAuthenticated": true
  },
  "traceId": "0HN…"
}

For tenant-scoped operations, verify that:

Olify-Tenant-Id contains exactly one valid GUID
The service account is authorized for that tenant
The token grants the permission required by the operation

Invalid tenant header values, multiple values, and unauthorized tenant GUIDs return 403, not 400.

Not found errors

When an entity cannot be found in the selected tenant, the API returns HTTP 404 with error set to EntityNotFoundException.

Verify the entity UUID and the selected tenant before retrying.

Server errors

HTTP 500 indicates an unexpected server failure and returns error set to Exception. Retry only when appropriate for your operation. If the failure persists, contact OLIFY and include the response traceId; it identifies the failed request in server diagnostics.

Responses with a different format

The token endpoint, POST /directory/connect/token, uses OAuth error JSON for failed token requests. For example, an incorrect client ID or client secret returns HTTP 400 from the token endpoint, not the OLIFY API error envelope.

Invalid OData query options can return an OData error response. Review Filter & sort for supported options and limits.