Error Reference

This guide is a reference for the errors you may encounter when using the Enterprise Context Engine Cloud Content Repository APIs. It covers the error response format, what each status code means for these APIs, the exact error messages each API returns, and how to locate a problem in the ingestion and graph pipeline.

Error Response Format

Most Cloud Content Repository API errors return a JSON body with this shape (the ECE Graph Query APIs use a different shape):

{
  "entity-type": "exception",
  "status": 400,
  "message": "Disallowed system property: sys_acl"
}

Fields

Field	Type	Description
entity-type	string	Always exception for error responses
status	integer	HTTP status code, repeated in the body
message	string	Human-readable explanation specific to this occurrence. The text varies by endpoint; the tables below list the messages you are likely to see.

ECE Graph Query API Errors

The ECE Graph Query APIs (/api/ece/business-objects/...) return this body instead:

{
  "code": "ECE-400-INVALID_PAGE_SIZE",
  "message": "limit 500 exceeds the maximum of 100",
  "details": [],
  "traceId": "ebab8cbf-9b7c-4b93-ba2e-0f7a0ccdabac"
}

Code	Status	Meaning
ECE-400-INVALID_PARAM	400	A parameter or the filter is malformed or invalid
ECE-400-INVALID_PAGE_SIZE	400	limit is above 100
ECE-401-UNAUTHENTICATED	401	Reserved for credential failures reported by the graph backend. A missing, malformed or expired token is rejected before the ECE APIs and returns 401 with an empty body.
ECE-404-NOT_FOUND	404	Unknown graph database (Unknown graphDBId: <id>), or, on GET .../{id} only, a Business Object that doesn't exist or the caller can't read (Business Object not found: <id>). For an unknown Business Object, the related, shared-attributes and provenance endpoints return 200 with an empty page.
ECE-422-UNSATISFIABLE_FILTER	422	The request is valid but cannot be satisfied
ECE-429-RATE_LIMITED	429	Throttled; retry after the Retry-After header
ECE-503-BACKEND_UNAVAILABLE	503	The backend is unavailable or the query timed out; retry with backoff after Retry-After
ECE-500-INTERNAL	500	Unexpected error; report the traceId

A search body that can't be parsed (malformed JSON, a value of the wrong type, or no body) and a missing permission are rejected before they reach the ECE APIs, so they return the standard body above (400, or 401 for a missing permission). A query parameter that isn't a number, such as limit=abc, does reach them and returns 400 ECE-400-INVALID_PARAM (For input string: "abc"). The page-size message reads limit N exceeds the maximum of 100 on search and limit N exceeds maximum of 100 on related.

Responses Without a JSON Body

Some errors have no JSON body, so always check the status code before parsing:

Situation	Status	Body
Missing, malformed or expired token	401	Empty — the request is rejected before it reaches the API
Unknown graph database (GET, DELETE, /config, /ontologyroutes)	404	Empty
Unsupported Accept type on a JSON endpoint, or Accept: text/plain on the pre-signed URL endpoint	406	Empty
Failed streaming download sent with Accept: application/octet-stream	500	Empty — send Accept: */* to get the real 404
Path-traversal sequences such as ..%2F.. in an embedding ID	403	HTML page from the gateway

HTTP Status Codes

2xx Success

200 OK

Request succeeded. The response body contains the requested resource, the query results, or — for GET /api/download/url/... — the pre-signed URL as plain text.

201 Created

A resource was created: a graph database (POST /api/graph/graphdbs, no Location header), an ontology (POST /api/graph/ontologies, with a Location header), entities or relationships, or a rebuild job (POST /api/v1/graph/rebuild, status SUBMITTED).

204 No Content

A delete succeeded (graph database or ontology), or a HEAD /api/download/... request found the blob.

206 Partial Content

A streaming download with a Range header returned the requested byte range with Content-Range.

304 Not Modified

A streaming download with If-None-Match or If-Modified-Since matched the current blob; there is no body.

4xx Client Errors

400 Bad Request

Cause: Invalid request data — an HXQL syntax error, an unsupported operator or property, a missing required field, or a value outside the allowed range.

{
  "entity-type": "exception",
  "status": 400,
  "message": "Error performing query: limit (100) + offset (9950) should be <= 10000 (10050)"
}

Solution:

• Read the message: it names the offending field, value or query position
• Check the error messages by API below for the cause and fix
• Invalid input is a generic message for a request body that could not be read (missing required field, wrong type, unknown enum value)

401 Unauthorized

Causes:

• Missing Authorization header — empty body
• Expired or malformed token — empty body
• On the graph APIs, a valid token that lacks the required permission — standard error body. This mapping is taken from the service's error handling; treat both 401 and 403 as "permission missing" in client code.

Solution:

• Request a new token (tokens last 15 minutes) and send it as Bearer <token>
• For graph APIs, compare the permissions in your token's hxp_authorization.permission with Permissions Required per API Group

403 Forbidden

Causes:

• The gateway blocks a request, for example an embedding ID containing ..%2F.. (HTML body)

Solution: Pass IDs exactly as returned by the API.

404 Not Found

Cause: The resource does not exist, or the caller cannot see it. The Query, Download and Embeddings APIs return 404 (not 403) for documents the caller has no access to.

{
  "entity-type": "exception",
  "status": 404,
  "message": "Ontology not found: 00000000-0000-0000-0000-000000000000"
}

Solution:

• Verify the ID and the base URL's {environment_id}
• Check the document's ACLs if a document you expect is missing
• Unknown graph databases return 404 with an empty body

406 Not Acceptable

Cause: The Accept header asks for a media type the endpoint does not produce.

{
  "entity-type": "exception",
  "status": 406,
  "message": "No acceptable representation"
}

Solution:

• JSON endpoints: application/vnd.hxcs.v1+json, application/vnd.hxcs+json or application/json
• Streaming download: application/octet-stream, application/vnd.hxcs+octet-stream, application/vnd.hxcs.v1+octet-stream or */*
• Pre-signed URL (GET /api/download/url/...): */* only

409 Conflict

Causes:

• An ontology with the same name already exists: "Ontology with name '<name>' already exists"
• An ontology is deleted while a graph database's ontology routes still reference it

{
  "entity-type": "exception",
  "status": 409,
  "message": "Ontology is still referenced by the ontologyRoutes configuration of graphDB(s): my-contracts-graph"
}

Solution: Use a different ontology name, or remove the ontology from the routes (PUT /api/graph/graphdbs/{graphDBId}/ontologyroutes) before deleting it.

413 Payload Too Large

Cause: The uploaded ontology file exceeds the configured size limit.

Solution: Reduce the size of the YAML file.

5xx Server Errors

500 Internal Server Error

Cause: An unexpected server-side error. A streaming download that fails while you send Accept: application/octet-stream also returns 500 with an empty body, because the service cannot write its JSON error.

Solution:

• For downloads, repeat the request with Accept: */* to see the real error (usually 404)
• Otherwise retry after a brief delay, and contact Hyland Support if it persists

501 Not Implemented

Cause: GET /api/download/url/... was called for a blob whose storage provider cannot produce pre-signed URLs.

Solution: Use the streaming download (GET /api/download/{docId}/...) instead.

503 Service Unavailable

Cause: The search index is unreachable. The search endpoints return 503 with a Retry-After header (seconds).

Solution:

• Retry after the number of seconds in Retry-After
• Implement retry logic with exponential backoff

Error Messages by API

The messages below were returned by the APIs. Values such as IDs and names vary with your request.

Query APIs

Status	Message	Cause	Fix
400	Query: SELECT * FROM SysContent WHERE, At position 1:30 mismatched input '<EOF>' expecting ...	HXQL syntax error; the position points at the problem	Fix the query at the reported position
400	Error performing query: limit (100) + offset (9950) should be <= 10000 (10050)	Offset pagination beyond 10,000 results	Page with searchAfter using the nextSearchAfter token
400	Disallowed system property: sys_acl	A security property (sys_acl, sys_racl, sys_secpol) used in a query	Remove it; these properties cannot be queried
400	Error performing OpenSearch query: failed to create query: Can only use phrase prefix queries on text fields - not on [cin_ingestProperties.BuyerOrg] which is of type [keyword]	LIKE 'Prefix%' on a keyword field (ingest properties, sys_name)	Use LIKE '%Prefix%', an _ wildcard, or =
400	Invalid input	searchAfter sent as an array	Send searchAfter as the string token from nextSearchAfter. (A POST /api/query body without query is not an error: it runs SELECT * FROM SysContent.)
400	Invalid expression: SELECT * FROM SysContent: At position 1:14 extraneous input 'SysContent' expecting <EOF>	An HXQL statement sent with "syntax": "expr"	Use "syntax": "hxql" (the default)
400	Query: SELECT COUNT(*) FROM SysContent, At position 1:13 extraneous input '*' expecting ...	Aggregate functions are not supported	Count with totalCount (trackTotalCountUpTo: -1) or termsAggregation
400	Query: SELECT * FROM SysContent LIMIT 5, At position 1:25 mismatched input 'LIMIT' expecting {<EOF>, 'WHERE', 'ORDER BY', ','}	LIMIT, GROUP BY or DISTINCT in HXQL	Use the body's limit / offset, and termsAggregation for grouping
400	Unsupported predicate operator: eq	Word-style operator in an advanced-query predicate	Use symbols such as =, <>, >=
400	Query: <statement>, No value for query parameter :st	A :param placeholder sent to POST /api/query, or a /advanced parameter with no value	Use POST /api/query/advanced with parameters
400	Error performing OpenSearch query: Can only use wildcard queries on keyword and text fields - not on [cin_ingestProperties.PageCount] which is of type [long]	termsAggregation on a numeric property	Aggregate on a string (keyword) property
400	Invalid input	POST /api/query/embeddings without vector, or termsAggregation without query / termsAggregationProperty	Add the missing field
400	Error performing OpenSearch query: failed to create query: Query vector has invalid dimension: 3. Dimension should be: 1024	Query vector length does not match the embedding model	Embed the question with the same model as sysembed_type
404	404 NOT_FOUND "Named query not found." (GET /api/query/named/{name}) / No named query with name nope (POST /api/query/named)	Unknown named query	List names with GET /api/query/named
503	—	Search index unreachable	Retry after Retry-After seconds

Queries that return 200 but no results

Some query mistakes do not raise an error. Naming fields in SELECT returns an empty documents list and totalCount: 0; ILIKE returned 0 results in the tested environment; STARTSWITH only matches the path hierarchy (for example sys_path); and ingest values are strings, so cinIsTld = TRUE matches nothing while cinIsTld = 'True' works. See Querying with HXQL.

Download and Embeddings APIs

Status	Message	Cause	Fix
404	No document found	Download of an unknown document ID, or no access	Check the ID and the document's ACLs
404	Could not find embedding with id <id> for document <docId>	Embedding lookup with an unknown document or embedding ID	Take both IDs from a vector search result
404	No blob found	The property path does not hold a blob	Use sysfile_blob or cin_blobs/{index}/blob
404	Could not find embedding with id nope for document 3f6d0b4e-...	Unknown embedding ID for that document	Use a sysembed_id returned by POST /api/query/embeddings
406	No acceptable representation	JSON Accept on a binary download	Send application/octet-stream or */*
406	— (empty body)	Accept: text/plain on the pre-signed URL endpoint	Send Accept: */*
406	No acceptable representation	A JSON Accept on the pre-signed URL endpoint	Send Accept: */*
500	— (empty body)	A failed streaming download sent with Accept: application/octet-stream	Repeat with Accept: */* to see the real error
501	—	The storage provider cannot produce a pre-signed URL	Use the streaming download

Ontology APIs

Status	Message	Cause	Fix
400	Required part 'ontologyName' is not present.	ontologyName missing or empty in the multipart upload	Send a non-empty ontologyName part
400	Required part 'file' is not present.	No file part in the upload	Attach the YAML file as file
400	Unsupported file type: 'notes.txt'. Only .yaml and .yml files are accepted.	Wrong file extension	Upload a .yaml or .yml file
400	'offset' must not be negative	Negative offset when listing	Use offset of 0 or more
400	Unknown ontologyId(s): nope	A route references an ontology that does not exist	Upload the ontology first, then use its ontologyId
400	Invalid condition for ontologyId '...': At position 1:7 token recognition error at: '= '	Route condition syntax error, for example = instead of ==	Use ==, !=, &&, || and double-quoted strings
400	Validation failed for argument [1] in public ...setOntologyRoutes(...)...	A route with a blank condition or ontologyId	Fill in both fields
404	Ontology not found: {ontologyId}	Unknown ontology ID	List ontologies with GET /api/graph/ontologies
404	— (empty body)	Unknown graph database on /config or /ontologyroutes	Check the graphDBId
409	Ontology with name '<name>' already exists	An ontology with that name already exists	Use a different name
409	Ontology is still referenced by the ontologyRoutes configuration of graphDB(s): my-contracts-graph	Deleting an ontology that a route still uses	Remove it from the routes first
413	—	Ontology file too large	Reduce the file size

Accepted but not valid

The ontology upload does not validate the YAML content, and PUT /ontologyroutes accepts a condition that references a bare property name such as sys_id == "...". The rebuild then fails with No global property: sys_id. Reference document properties as content.<property>, for example content.sys_primaryType == "SysFile".

GraphDB APIs

Status	Message	Cause	Fix
400	GraphDBConfig with name 'my-knowledge-graph' already exists	Duplicate graph database name	Use a different graphDBName
400	GraphDBConfig name must not be null or blank	Missing or blank graphDBName	Provide a name
400	Invalid input	Unknown version (for example "1.0"), or both graphDBName and domainName sent	Use "v2", and only graphDBName
400	—	The maximum number of graph databases has been reached (100 by default)	Delete an existing graph database first
400	'offset' must not be negative	Negative offset when listing	Use offset of 0 or more
400	Aggregate queries are only supported for GQL schema	/aggregate on a deprecated v1 graph database	Use a v2 graph database
400	Configuration not found for GraphDBConfig: <id>	/aggregate on an unknown graph database (400, not 404)	Check the graphDBId
400	Property 'title' of type 'Document' is not groupable. Only Int/Float properties, properties with @search(by: [exact]), or DateTime properties with an @search directive are supported.	Aggregating on a non-groupable property	Group by a groupable property such as entity_type
404	— (empty body)	Unknown graph database	Check the graphDBId

Graph Rebuild APIs

Status	Message	Cause	Fix
400	Unknown state 'failed'. Valid values: [UNKNOWN, SCHEDULED, SCROLLING_RUNNING, RUNNING, COMPLETED, ABORTED]	Unknown state filter when listing jobs	Use one of the listed states (case-insensitive)
400	'limit' must not be negative / 'offset' must not be negative	Negative paging values	Use 0 or more
400	Invalid rebuild mode: BOGUS	Unknown rebuildMode	Use STANDARD, EVENT_ONLY or FORCE_REPROCESS
400	query and graphDBId cannot be combined: graphDBId only narrows the auto-generated query, so it has no effect on a query you supply yourself. Supply one or the other.	Both query and graphDBId sent	Send one or the other
400	Invalid query: At position 1:13 missing {IDENTIFIER, FROM_IDENTIFIER} at '<EOF>'	Invalid HXQL in query	Fix the query
400	Query is required (no graphDB matches graphDbId: 00000000-0000-0000-0000-000000000000)	Unknown graphDBId	Check the ID
400	Query is required (no ontology routes configured for auto-generation)	The graph database has no routes	Set ontology routes, or send a query
400	No global property: sys_id	A route condition uses a bare property name	Reference document properties as content.<property>
404	Rebuild graph task not found: kgRebuild:00000000-0000-0000-0000-000000000000	Unknown job ID	Use the jobId from the create response

Diagnosing by Pipeline Stage

When something is not working, these APIs help you pinpoint where in the pipeline things broke:

Stage	What Could Go Wrong	How to Diagnose
Authentication	401 on any API call	A 401 with an empty body means the token is missing, malformed or expired: decode the JWT and check exp and hxp_authorization.environment_id. On graph APIs, a 401 with a "entity-type": "exception" body means the token is valid but lacks the required permission (for example content-lake-api.graph-configs.create); compare with the token's hxp_authorization.permission. See Authentication.
Ingestion	Document not appearing in search	Call GET /api/query/waitForFullTextSearchIndexing to confirm indexing is done. Query by sys_id with SELECT * to check if the document exists.
Data Curation	Missing chunks or embeddings	Run POST /api/query/embeddings with query filtered to the document's sys_id: no results means curation has not produced embeddings. (cinctx_contextPropertyNames shows which context enrichments ran, not curation.) Verify the document's cin_ingestProperties for ingestion metadata.
GraphDB / Ontology Setup	Graph config or routes misconfigured	Call GET /api/graph/graphdbs/{graphDBId}/config to inspect the current graph configuration, including its ontologyRoutes. Check that each route's condition matches your content.
Graph Build	Build job aborted or stalled	Call GET /api/v1/graph/rebuild/{jobId} to check the job's status and errorMessage. List jobs with GET /api/v1/graph/rebuild?state=ABORTED to find aborted builds. Valid state values: SCHEDULED, RUNNING, SCROLLING_RUNNING, COMPLETED, ABORTED, UNKNOWN.
KG Processing	Documents not appearing in graph retrieval	Query WHERE cinctx_kgProcessingStates/*/ontologyId = '<graphDBId>_<ontologyId>' to find documents processed for an ontology in a graph DB, then check the status of each entry. Find failures with WHERE cinctx_kgProcessingStates.status = 'SYNC_FATAL_FAILURE', and use termsAggregation on cinctx_kgProcessingStates.status for a status breakdown (aggregations need the dot form, not /*/).
Business Object Retrieval	Empty results from ECE Graph Query	Check that you are querying the right graph database (graphDBId), that the graph build completed, and that the ontology defines the entity types you are filtering on. Results are also limited to what the caller can read.
HXQL Queries	Queries returning 0 results unexpectedly	Use SELECT *. Naming fields in SELECT makes POST /api/query return an empty documents list. Type any fields (e.g., cinctx_contextProperties) work in WHERE with dot-notation. On array fields, = and IN() both match if any element matches.

tip

Key debugging pattern: Start with SELECT * FROM SysContent WHERE sys_id = 'your-doc-id' to see everything about a specific document — its mixins, ingest properties, context enrichments, and KG processing states. This tells you exactly where in the pipeline the document sits.

Troubleshooting Guide

Debug Workflow

Getting Help

Before Contacting Support

Gather the following information:

1. Request Details

   • HTTP method and endpoint
   • Request headers (sanitize tokens)
   • Request body (sanitize sensitive data)

2. Response Details

   • HTTP status code
   • Response headers
   • Error response body

3. Environment

   • API base URL
   • Client library and version
   • Timestamp of the error
   • Environment ID

4. Steps to Reproduce

   • Sequence of API calls
   • Any relevant context