Best Practice - Global API Exception Handling

Introduction

Effective Nexus 1, CMiC has introduced centralized error handling across all APIs. This ensures every API response follows a consistent, structured JSON format, making errors easier to trace, debug, and handle across all services.

Each error message is automatically logged in CMiC with a unique UUID for traceability during runtime.

Why this change?

Previously, each module or service implemented its own error-handling logic, which led to:

• Inconsistent error response formats (plain text or JSON)
• Hidden exceptions
• Unreliable HTTP status codes

Responses may include only HTTP status code such as 400 Bad request or 500 Internal Server Error, without a detailed message or structure. In some cases, responses may differ in format (plain text or JSON) and may not include a CMiC error code or explanation of what went wrong, making it difficult to diagnose issues.

Examples of Current Error Messages:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

HTTP/1.1 500 Internal Server Error
Content-Type: text/plain
Internal Server Error

What's New?

All APIs now return standardized error responses in the following JSON format:

Example JSON Error Message as of Nexus 1 :

    "uuid": "e45214f8-5b11-4987-a1a6-7313d5fa6e0f",
    "status": "Error",
    "errorCode": "WSD-0000",
    "errorMessage": "Could not determine if the user is an internal user.",
    "timestamp": "2025-09-02 18:58:25.369",
    "moreDetails": {
        "ecid": "30393979-77ef-4887-9aaf-738475548f09-000003c6"
    }
}

Recommendations

If your integration consumes API error responses, please review and update your error-handling logic to ensure compatibility with the new format.