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:
Field Definitions & JSON sample
| Attribute | Type | Description |
|---|---|---|
| uuid | String | Unique ID for finding the error in a CMiC log entry |
| status | String | 'Error' by default |
| errorCode | String | Uses CMiC error code, message key, or custom value. |
| errorMessage | String | Error message |
| timestamp | Timestamp | Time when the error occurred |
| moreDetails | Map | Optional: extra information where applicable |
| ecid | String | Oracle tracking Uuid, can we be used to further diagnose Oracle logs |
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.