---
title: ExceptionHandler
summary: API reference for ExceptionHandler.
status: draft
owner: bendy
last_reviewed: 2026-09-15
library: SAIF.Web.API.Clients
reference_type: package
---

# ExceptionHandler

`ExceptionHandler` is a stateless static component that guards HTTP response success and translates failing responses into typed exceptions from [SAIF.Web.API.Core](../../../saif-web-api-core/overview.md)'s `SAIF.API.Exceptions.*` hierarchy, so consumers of `JsonHttpClient` catch domain exceptions rather than transport or RestSharp types.

## Purpose
- Decide whether a completed `IRestResponse` represents success or failure, and short-circuit (return normally) for success ([BR-CLI-006](../../business-rules.md#br-cli-006-non-success-response-failure-conversion)).
- Select the most informative available error text from a failing response, preferring the API's own error payload ([BR-CLI-008](../../business-rules.md#br-cli-008-exception-message-source-preference), [BR-CLI-017](../../business-rules.md#br-cli-017-failure-message-source-selection)).
- Map an HTTP status code to a specific `SAIF.API.Exceptions.*` type and throw it ([BR-CLI-007](../../business-rules.md#br-cli-007-http-status-to-exception-type-mapping)).

## Context
- Namespace: `SAIF.Web.API.Clients`
- Assembly/package: `SAIF.Web.API.Clients` (NuGet package `SAIF.Web.API.Clients`)

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `EnsureSuccessfulResponse` | `static void EnsureSuccessfulResponse(IRestResponse response)` | Throws a mapped `SAIFException` when the response status is `< 200` or `>= 400`; returns normally otherwise. 3xx redirects pass as success. See [EnsureSuccessfulResponse](../../operations/ensure-successful-response.md). |
| `ToKnownError` | `static void ToKnownError(HttpStatusCode status, string content)` | Extracts an error message from the payload and throws a typed `SAIF.API.Exceptions.*` exception; never returns normally. See [ToKnownError](../../operations/to-known-error.md). |

## Behavioral notes
- `GetContent(IRestResponse response)` (private) selects the best available error text from `Content` / `ErrorMessage` / `ErrorException` / status description; its nested `ErrorMessage` check is inverted relative to the enclosing guard, so the `ErrorException.Message` path is effectively unreachable and a transport failure with no `Content` yields a blank error message*.
- `ToKnownError` harvests error text by scanning top-level JSON token paths for `errormessage`, `exceptionmessage`, `message`, or `usermessage`; a parse failure of `content` falls back to using the raw content as the message.
- HTTP `404` maps to `NoMatchingDataException`; `401`/`403` map to `UnauthorizedAccessException`; `400` maps to `InvalidDataException`; every other status (including `0`) maps to `InternalServerError`.

## Constraints and usage notes
- Both public members are `static`; there is no instance state to configure.
- `ToKnownError` is public and may be called directly by consumers, not only via `EnsureSuccessfulResponse`.

> **Note:** Statements marked with `*` were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts.

## Sources
- `src/SAIF.Web.API.Clients/ExceptionHandler.cs`