Skip to content

Translate HTTP failure to typed exception

This operation inspects an IRestResponse's status code and body, and either returns normally (success) or throws a specific SAIFException subtype carrying the original HTTP status code.

Field Value
Operation ID OP-03
Trigger Step 9 of Execute JSON API request and return typed envelope, when EnsureSuccessfulResponse is true; also directly callable as ToKnownError.
Inputs IRestResponse (status code and body content).
Outputs A thrown SAIFException subtype carrying HttpStatusCode; returns normally when the status is 200–399.
Primary components ExceptionHandler.EnsureSuccessfulResponse, ExceptionHandler.ToKnownError, ExceptionHandler.GetContent
Entry point src/SAIF.Web.API.Clients/ExceptionHandler.cs

Steps

  1. Evaluate status: status < 200 || status >= 400 → continue; otherwise return normally (BR-16).
  2. Select message source (GetContent): response.Content when nonblank; otherwise a fallback chain that does not reliably return ErrorMessage/ErrorException.Message as a clean precedence — see BR-17 for the verified branch-by-branch behavior, including the apparent defect where a lone nonblank ErrorMessage or a lone ErrorException is discarded.
  3. This step delegates to a package dependency operation retrieved via the Legends CLI RAG service.
  4. Checks whether the candidate message is null or whitespace-only.†

Origin: Step 2.1† is implemented in IsNullOrWhiteSpace in SAIF.Framework.Common (retrieved via the Legends CLI RAG service) and executed on behalf of this operation. 3. Parse structured error: JToken.Parse(content); accumulate tokens whose path is errormessage, exceptionmessage, message, or usermessage (case-insensitive) (BR-18). 4. Fallback message: if the accumulated text is blank, or parsing threw, use the raw content (BR-19). 5. Map to exception type: 404 → NoMatchingDataException; 401/403 → UnauthorizedAccessException; 400 → InvalidDataException; all other statuses → InternalServerError; each initialized with HttpStatusCode = status (BR-20). - Constructs the selected exception type from the SAIFException hierarchy defined in SAIF.Web.API.Core, an in-run local project dependency.

Process flow

The following diagram visualizes this operation's control flow.

flowchart TD
    Start([Response received]) --> D1{Status in 200-399?}
    D1 -->|Yes| EndOk([Return normally])
    D1 -->|No| S1[Select message source]
    S1 --> S2["Parse structured error<br>content"]
    S2 --> D2{Message extracted?}
    D2 -->|No| S3[Fall back to raw content]
    D2 -->|Yes| S4["Map status to exception<br>type"]
    S3 --> S4
    S4 --> EndErr(["Throw typed<br>SAIFException"])

Failure and edge-case behavior

  • 401 (Unauthorized) is included in the default RetryOnStatusCodes set consumed by Execute JSON API request and return typed envelope, so an authentication failure is retried up to 3 times (with a 1-second default delay) before this operation raises the exception.

Note: Statements marked with † were retrieved from dependency library documentation via the Legends CLI RAG service. They describe inherited behavior from the indicated origin library and should be verified if the dependency version changes.

Sources

  • src/SAIF.Web.API.Clients/ExceptionHandler.cs
  • src/SAIF.Web.API.Core/SAIFException.cs