Error Reference

This guide provides a comprehensive reference for errors you may encounter when using Knowledge Discovery APIs, along with troubleshooting steps and solutions.

Error Response Format

All Knowledge Discovery API errors follow the RFC 7807 Problem Details specification:

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The 'name' field is required and cannot be empty"
}

Fields

Field	Description
type	URI reference identifying the problem type
title	Short, human-readable summary of the problem
status	HTTP status code
detail	Human-readable explanation specific to this occurrence
traceId	(Optional) Trace identifier for debugging and support
errors	(Optional) Dictionary of validation errors for 400 Bad Request

HTTP Status Codes

2xx Success

200 OK

Request succeeded. Response body contains the requested resource.

{
  "id": "agent-id",
  "name": "Customer Support Agent",
  ...
}

202 Accepted

Request accepted for processing. Used for asynchronous operations like question submission.

HTTP/1.1 202 Accepted

4xx Client Errors

400 Bad Request

Cause: Invalid request payload, validation errors, or malformed JSON.

Common Scenarios:

Missing Required Fields

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The 'name' field is required and cannot be empty"
}

Solution: Ensure all required fields are present and non-empty.

Invalid Field Values

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The field 'modelName' must be a valid model identifier"
}

Solution: Verify field values match expected formats and valid options.

Invalid GUID Format

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "The value 'invalid-id' is not a valid GUID"
}

Solution: Ensure GUIDs are properly formatted (e.g., 123e4567-e89b-12d3-a456-426614174000).

Invalid Filter Expression

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid filter operator 'InvalidOperator' for field type 'Text'"
}

Solution: Use valid operators for the field type. See Filter Syntax Reference.

Validation Errors

When multiple validation errors occur, the response includes an errors dictionary:

{
  "type": "https://datatracker.ietf.org/doc/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "requestDto": [
      "The requestDto field is required."
    ],
    "$.type": [
      "The JSON value could not be converted to Hyland.Experience.AI.Data.KnowledgeRetrieval.Shared.Contracts.Agents.Filters.FieldType. Path: $.type | LineNumber: 2 | BytePositionInLine: 15."
    ]
  },
  "traceId": "00-955695f93b6bf758ccf8b163325e4083-91e42eaf5fda926d-00"
}

Solution: Review each error in the errors dictionary and correct the corresponding fields.

401 Unauthorized

Cause: Missing, invalid, or expired authentication token.

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7235#section-3.1",
  "title": "Unauthorized",
  "status": 401,
  "detail": "The access token is invalid or expired"
}

Solutions:

1. Missing Token

   # Ensure Authorization header is present
   curl -H "Authorization: Bearer YOUR_TOKEN" ...

2. Expired Token

   • Refresh your access token using the refresh token
   • Re-authenticate if refresh token is also expired

3. Invalid Token

   • Verify token is correctly copied
   • Check for extra whitespace or newlines
   • Ensure token hasn't been revoked

403 Forbidden

Cause: Authenticated but not authorized to perform the requested operation.

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.3",
  "title": "Forbidden",
  "status": 403,
  "detail": "User does not have permission to access this agent"
}

Common Scenarios:

Insufficient Role Permissions

Problem: User has Discovery User role but attempts to create an agent.

Solution: Request Discovery Agent Manager role from your administrator.

Agent Access Rights

Problem: User attempts to access an agent they don't have rights to.

Solution:

• Verify user or user's group is in the agent's accessRights
• Request access from the agent owner
• Use agent list API to see accessible agents only

Source Access Denied

Problem: User attempts to use a source they don't have access to.

Solution: Contact administrator to grant access to the required data source.

404 Not Found

Cause: Requested resource doesn't exist or user doesn't have access to it.

{
  "type": "https://datatracker.ietf.org/doc/html/rfc9110#section-15.5.5",
  "title": "Not Found",
  "status": 404,
  "detail": "Entity AgentConfiguration with id e5cbf54a-2a4c-4c61-817e-17f10c8a8fe0 not found",
  "traceId": "0HNGT49SEDKRI:00000001"
}

Common Scenarios:

Agent Not Found

Causes:

• Agent ID is incorrect
• Agent has been deleted
• User doesn't have access (403 may also be returned)

Solution:

// List accessible agents first
var agents = await GetAgentsAsync();
if (agents.Any(a => a.Id == agentId))
{
    // Agent exists and is accessible
}

Question/Answer Not Found

Causes:

• Question ID is incorrect
• Answer not yet generated (still processing)
• Question has expired or been deleted

Solution: Implement retry logic with polling for asynchronous operations.

Source Not Found

Causes:

• Source ID is incorrect
• Source has been removed

Solution: Verify source IDs with your data ingestion team.

409 Conflict

Cause: Request conflicts with the current state of the resource.

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.8",
  "title": "Conflict",
  "status": 409,
  "detail": "A concurrent update has occurred. Please retrieve the latest version and retry."
}

Scenario: Concurrent agent updates.

Solution:

1. Retrieve the latest version of the resource
2. Reapply your changes to the latest version
3. Retry the update operation

5xx Server Errors

500 Internal Server Error

Cause: Unexpected server-side error.

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.1",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred while processing your request"
}

Solution:

• Retry the request after a brief delay
• If persists, contact Hyland Support with:
  • Request ID (from response headers)
  • Timestamp
  • Request details (sanitized)

502 Bad Gateway

Cause: Upstream service unavailable or returned invalid response.

Solution:

• Retry with exponential backoff
• Check service status page
• Contact support if persistent

503 Service Unavailable

Cause: Service temporarily unavailable (maintenance, overload).

{
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.6.3",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "The service is temporarily unavailable. Please retry later."
}

Solution:

• Implement retry logic with exponential backoff
• Check for Retry-After header
• Monitor service status

504 Gateway Timeout

Cause: Request took too long to process.

Solution:

• For question submissions: This is unusual as they're async (202)
• For answer retrieval: Answer may still be processing, retry
• Check for issues with filters or data sources causing slow queries

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
   • Request/Trace ID

3. Environment

   • API base URL
   • Client library and version
   • Timestamp of the error
   • ClientId
   • EnvironmentId/Key

4. Steps to Reproduce

   • Sequence of API calls
   • Any relevant context