Error Handling

API Fundamentals

Error Handling

A resilient LCE client evaluates the HTTP result and the service response envelope. Preserve useful diagnostics, classify retryable failures and avoid exposing sensitive request data.

Two layers of outcome

Layer	What it represents	Client action
HTTP status	Transport, authentication, gateway and protocol outcome.	Handle non-2xx responses before parsing a successful domain result.
Service envelope	Business or service outcome represented by fields such as `type`, `code`, `message` and `errors`.	Inspect the envelope even when an operation returns HTTP 200.

Service error shape

{
  "type": "Error",
  "code": "<service-code>",
  "message": "The request could not be completed.",
  "errors": [
    "A supplied field is invalid."
  ],
  "details": "<additional diagnostic detail>",
  "result": null
}

This is an abbreviated shape based on common service-response fields. The exact envelope and populated properties depend on the operation.

Service response types

Type	Interpretation
`Success`, `Completed`, `Approved`	The operation reached a successful or approved business outcome. Validate the expected result.
`Pending`, `Redirected`	The workflow is not represented as a final synchronous success. Follow domain-specific instructions.
`Declined`	The request reached a negative business outcome. Do not automatically classify it as a technical retry.
`Timeout`	The outcome may be uncertain. Verify state before retrying a side-effecting operation.
`Error`, `Unknown`	Treat as unsuccessful and capture safe diagnostic information for investigation.

Recommended handling flow

Check the HTTP status. Separate authentication, authorization, validation, throttling and server failures where the response provides that distinction.
Parse the expected schema. If the body cannot be parsed, retain the HTTP status and a safely truncated body for diagnostics.
Inspect the service type. Do not treat every HTTP 200 envelope as a successful business result.
Capture context. Record operation ID, safe resource identifiers, timestamp and available thread or correlation data.
Choose a recovery action. Fix invalid input, renew credentials, wait, verify the resource state or escalate based on the failure class.

Safe diagnostics

Log the endpoint operation, HTTP status and service code.
Preserve message and errors when they contain no sensitive data.
Never log JWTs, authorization headers, payment data or customer secrets.
Do not expose raw details, inner responses or service logs directly to end users.
Use a user-safe message while retaining technical context in protected logs.