API Error Handling¶

Understand, investigate, and document failures across the WhiteLotusAI API gateway, application services, and external integrations.

1. Error handling overview¶

API failures can originate at different layers. Identifying the source helps determine which component, logs, configuration, or tests should be investigated.

flowchart TD
    REQUEST(["Incoming API Request"])

    subgraph APP["WhiteLotusAI Application"]
        GATEWAY["REST API Gateway"]
        VALIDATE["Request Validation"]
        AUTH["Authentication and Authorization"]
        SERVICE["Application Service"]
        HANDLER["Exception Handling"]
    end

    PROVIDER["External Integration Provider"]
    RESPONSE(["HTTP Response"])

    REQUEST --> GATEWAY
    GATEWAY --> VALIDATE
    VALIDATE --> AUTH
    AUTH --> SERVICE
    SERVICE --> PROVIDER

    VALIDATE -. "Validation failure" .-> HANDLER
    AUTH -. "Access failure" .-> HANDLER
    SERVICE -. "Service failure" .-> HANDLER
    PROVIDER -. "Provider failure" .-> HANDLER

    HANDLER --> RESPONSE
    SERVICE --> RESPONSE

    classDef entry fill:#e8eefc,stroke:#4969a8,color:#172b4d,stroke-width:1.5px
    classDef application fill:#e5f4ec,stroke:#34845b,color:#153d2a,stroke-width:1.5px
    classDef failure fill:#fff0dc,stroke:#bd7b24,color:#633b08,stroke-width:1.5px
    classDef external fill:#f0e8fb,stroke:#8055ad,color:#382052,stroke-width:1.5px

    class REQUEST,RESPONSE entry
    class GATEWAY,VALIDATE,AUTH,SERVICE application
    class HANDLER failure
    class PROVIDER external

    style APP fill:transparent,stroke:#80CBC4,stroke-width:1.5px

2. Error categories¶

2.1 Authentication errors¶

Authentication failures occur when credentials are missing, invalid, expired, or otherwise unacceptable.

Examples to investigate:

• Missing authentication credentials.
• Invalid or malformed access tokens.
• Expired access tokens.
• Invalid refresh-token requests.
• Revoked, expired, or unavailable integration credentials.

Record the actual HTTP status and response schema from the relevant route, middleware, or integration handler.

2.2 Authorization errors¶

Authorization failures occur when an authenticated identity is not permitted to perform an operation or access a resource.

Verify:

• Resource ownership and tenant boundaries, where applicable.
• Role-based access checks for administrative operations.
• Permissions for sessions, uploaded documents, and integration connections.
• Whether inaccessible resources are intentionally presented as not found.
• Whether authorization checks are enforced server-side.

A successful login must never be treated as sufficient authorization to access another user's data.

2.3 Request-validation errors¶

Validation failures occur when a request does not satisfy the endpoint's declared schema or validation rules.

The gateway declares request-validation handling and documents a 422 response in its API configuration.

For each endpoint, establish:

• Required and optional fields.
• Accepted data types, formats, and enumerated values.
• Missing-field and invalid-value behaviour.
• Pagination and identifier constraints.
• Uploaded-file type and size restrictions.
• The actual error response structure.

Do not assume that validation behaviour is identical across the gateway, chat service, and integrations service.

2.4 Resource-not-found errors¶

An HTTP 404 response may indicate that the requested route or resource does not exist.

During investigation, verify:

• Whether the route is registered.
• Whether the resource exists.
• Whether it belongs to the requesting user.
• Whether resource visibility is intentionally restricted.
• Whether the observed response matches the endpoint's documented contract.

The gateway declares 404 response documentation, but individual routes and services still require verification.

2.5 Integration-provider errors¶

WhiteLotusAI integrations may depend on external systems such as Google services, Atlassian Jira, Slack, and Microsoft Graph.

These are possible failure categories, not claims that every category is currently handled consistently.

Document how each integration translates provider failures into WhiteLotusAI responses. Where behaviour is undefined or unverified, record an open finding.

2.6 Internal-service errors¶

A request can fail while the gateway communicates with a downstream application service, even if the original request is valid.

Investigate:

• Downstream service availability and connectivity.
• Internal-service authentication.
• Connection and response timeouts.
• Retry attempts and retry limits.
• Status-code propagation or transformation.
• Exception handling at service boundaries.
• Whether internal details are exposed to the caller.

Do not include internal hostnames, credentials, stack traces, or sensitive infrastructure details in public-facing error responses.

2.7 Unexpected server errors¶

Unexpected exceptions may indicate defects, unhandled edge cases, configuration errors, or dependency failures.

The gateway registers an unexpected-exception handler. Its precise response format, logging behaviour, and interaction with downstream services require implementation-level verification.

Client-facing responses should explain that a request failed without exposing sensitive internals. Detailed diagnostics should be recorded in appropriately protected operational logs.

3. Error response documentation standard¶

Document each endpoint's error behaviour using verified implementation evidence.

Example: documenting an observed response¶

Use the following as a template, replacing the placeholders with a response captured from the actual implementation.

{
  "status": "<observed HTTP status>",
  "error": "<observed error code, if present>",
  "message": "<observed client-facing message>",
  "details": "<observed safe details, if present>",
  "request_id": "<observed request identifier, if present>"
}

Important: This JSON is illustrative, not a claim about WhiteLotusAI's current response schema. Do not publish it as an API contract until the implementation has been verified.

For every documented response, capture the endpoint, HTTP method, observed status, response body, and relevant evidence.

4. Retry and recovery¶

Retry behaviour must depend on the failure category and the operation being performed.

The presence of an HTTP client retry mechanism does not prove that retries are safe for every operation. Verify retry conditions, backoff behaviour, attempt limits, and duplicate-effect protection.

5. Security and privacy¶

Error responses, application logs, and diagnostic captures must be reviewed for accidental disclosure.

Protect the following information:

• Access tokens, refresh tokens, and OAuth credentials.
• API keys, client secrets, passwords, and authentication material.
• Email content, private documents, and message bodies.
• Sensitive external-provider responses.
• Internal stack traces, file paths, and infrastructure details.
• Personal information that is unnecessary for troubleshooting.

For integration failures, preserve enough sanitized context to investigate the issue without storing secrets or unnecessarily duplicating private user data.

6. Troubleshooting workflow¶

Follow this sequence when investigating an API error.

flowchart TD
    A(["Capture the Failure"])
    B["Record Endpoint, Method, Status and Time"]
    C["Sanitize Request and Response"]
    D["Identify the Failing Layer"]
    E["Inspect Handler, Validation and Service Client"]
    F["Compare with Documented Contract"]
    G{"Reproduced and Explained?"}
    H["Record Finding and Add Regression Test"]
    I["Mark as Open or Unverified"]

    A --> B --> C --> D --> E --> F --> G
    G -->|Yes| H
    G -->|No| I

    classDef start fill:#e8eefc,stroke:#4969a8,color:#172b4d,stroke-width:1.5px
    classDef process fill:#e5f4ec,stroke:#34845b,color:#153d2a,stroke-width:1.5px
    classDef decision fill:#fff0dc,stroke:#bd7b24,color:#633b08,stroke-width:1.5px
    classDef pending fill:#f0e8fb,stroke:#8055ad,color:#382052,stroke-width:1.5px

    class A start
    class B,C,D,E,F,H process
    class G decision
    class I pending

1. Record the endpoint, HTTP method, timestamp, and returned status.
2. Capture a sanitized request and response, excluding credentials and private payloads.
3. Determine whether the failure originated in the gateway, chat service, integrations service, or an external provider.
4. Review the relevant route handler, validation model, exception handler, and service client.
5. Check authentication, authorization, configuration, and provider connectivity as appropriate.
6. Compare the observed response with the documented API contract.
7. Record whether the issue is reproduced, resolved, or remains unverified.
8. Add a regression test when appropriate during implementation and testing.

This workflow supports investigation and documentation; it does not imply that an underlying defect has been corrected.

7. Current verification status¶

The current source-derived baseline confirms that the gateway registers several exception-handling mechanisms and declares 404 and 422 response documentation.

The following items remain open verification findings.

Close a finding only when the relevant implementation, automated tests, or runtime evidence supports the documented conclusion.

8. Related documentation¶

• API Reference Overview — API architecture and service boundaries.
• Read-Only Integration Policy — Integration access restrictions.
• Security Overview — Security responsibilities and controls.
• Threat Model — Threats, trust boundaries, and mitigation considerations.

9. Maintenance¶

Update this document whenever verified implementation changes affect:

• HTTP status codes or response schemas.
• Authentication and authorization behaviour.
• Provider-error mapping and recovery.
• Timeout and retry policies.
• Logging, redaction, and correlation identifiers.

Keep proposed standards separate from implemented behaviour. Mark unverified details explicitly until supported by source review, automated tests, or runtime evidence.

Documentation principle: Describe observed behaviour as fact, proposed behaviour as guidance, and unverified behaviour as an open finding.