---
title: "Best Practice | Global API Exception Handling"
slug: "best-practice-global-api-exception-handling"
updated: 2025-10-16T15:26:12Z
published: 2025-10-16T15:26:12Z
canonical: "developers.cmicglobal.com/best-practice-global-api-exception-handling"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://developers.cmicglobal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

          

#### 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.