# Error Handling

> [!note] Bu sayfa henüz çevrilmedi ve İngilizce olarak gösteriliyor.


All Elements Hub endpoints return a uniform JSON error response when a request cannot be fulfilled. The response carries enough information for a client to react programmatically (a stable, machine-readable `errorCode`) as well as for a human to debug the issue (a `message` and an `errorUrl`).

### Response Format

Every error response uses the same `ErrorInfo` schema, regardless of which endpoint produced the error:

```json
{
  "httpStatusCode": 404,
  "errorCode": "E5",
  "errorUrl": "https://id.rhopointservice.com/E5",
  "message": "No connected device was found with identifier '12f1d7dd07ac42a088c8f961b39d68ff'.",
  "exceptionType": "ConnectedDeviceNotFoundException",
  "stackTrace": null,
  "innerError": null,
  "details": null
}
```

| Field | Type | Description |
| --- | --- | --- |
| `httpStatusCode` | int | The HTTP status code of the response (also present in the response headers). |
| `errorCode` | string | Stable, machine-readable identifier of the form `E<n>` (e.g. `E5`, `E42`). The single source of truth for what failed. Document and react to this value in your client. |
| `errorUrl` | string \| null | Permanent URL with details about the error, of the form `https://id.rhopointservice.com/<errorCode>`. |
| `message` | string | Human-readable explanation of the failure, often with the offending identifier or value interpolated. |
| `exceptionType` | string \| null | The .NET exception type that produced the error. Useful for support tickets but should not drive client logic — use `errorCode` instead. |
| `stackTrace` | string \| null | Only populated in development builds. Always `null` in production. |
| `innerError` | object \| null | If the error wraps another error, a nested `ErrorInfo` describing the cause. |
| `details` | object \| null | Additional contextual information about the error as a free-form key/value map (e.g. parameter that failed validation). |

### The `errorUrl` Pattern

Every `errorCode` resolves to a dedicated page under `https://id.rhopointservice.com/`. For example:

- `https://id.rhopointservice.com/E5` — connected device not found
- `https://id.rhopointservice.com/E42` — invalid `imageFormat` parameter
- `https://id.rhopointservice.com/E16` — unrecognised container format

The page is the authoritative reference for each code and is kept in sync with the codebase. Treat it as your primary lookup when you encounter an unfamiliar `errorCode`. Linking directly to this URL from your own application's error UI is encouraged — the URL is stable across hub releases.

### How to React on the Client

Recommended pattern:

1. Parse the response body as JSON whenever the HTTP status is in the `4xx` or `5xx` range.
2. Switch on `errorCode` — not on `message` and not on `exceptionType` — to drive recovery logic.
3. Surface `message` (and optionally `errorUrl`) in user-facing error displays.
4. Log the full `ErrorInfo` payload, including `innerError`, for support and debugging.

Example client-side handling:

```bash
curl -i http://localhost:42042/v1/devices/does-not-exist
```

```http
HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "httpStatusCode": 404,
  "errorCode": "E5",
  "errorUrl": "https://id.rhopointservice.com/E5",
  "message": "No connected device was found with identifier 'does-not-exist'.",
  "exceptionType": "ConnectedDeviceNotFoundException",
  "stackTrace": null,
  "innerError": null,
  "details": null
}
```

### Validation Errors from ASP.NET

In addition to `ErrorInfo` responses, a small number of endpoints — those that use built-in ASP.NET model validation — may return the standard `ProblemDetails` format on HTTP `400 Bad Request` when a request body is structurally invalid (missing required field, wrong type). These responses look like:

```json
{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "DeviceIdentifier": [ "The DeviceIdentifier field is required." ]
  }
}
```

Treat `ProblemDetails` as an indicator that the request never reached business logic — fix the request shape, then retry. Business-logic errors always use the `ErrorInfo` format above.

### Testing Error Handling

The hub exposes a dedicated endpoint to provoke each major error category, useful for verifying client-side handling:

```http
POST /v1/system/errors/raise-exception
Content-Type: application/json

{ "errorType": "device" }
```

| `errorType` | Triggers |
| --- | --- |
| `device` | A simulated device-layer exception (`ErrorInfo`, with a non-zero `errorCode`). |
| `notfound` | An HTTP 404 with `ErrorInfo`. |
| `unhandled` | An uncaught exception, exercising the global exception handler. |

Use these in your integration tests to ensure your client correctly parses `ErrorInfo` and reacts on `errorCode`, not on transport-level details.

### Best Practices

- React on `errorCode`, not on `message` text — the message is localisable and may change between releases. The `errorCode` is contractually stable.
- Always log `innerError` chains in full. The root cause is often deeper than the top-level message suggests.
- For user-facing dialogs, show `message` and link to `errorUrl`. Do not surface `exceptionType` or `stackTrace` to end-users.
- Treat any `5xx` response as transient unless `errorCode` indicates otherwise — retry with backoff before failing the operation.
- Treat any `4xx` response (except `408`, `429`) as a permanent failure of that request — fix the request before retrying.