API Error Handling

Executive Summary

API Error Handling defines the logical error response standard for Algosure APIs. Errors must be predictable, auditable, safe for clients, and useful for mobile, web, AIOS, and integration consumers.

Why This Exists

Inconsistent errors create poor user experiences, weak observability, and integration ambiguity. Algosure needs a standard error model before endpoint specs are created.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Consistent errors reduce client complexity, improve supportability, and prevent sensitive details from leaking through API responses.

Error Response Standard

Every API error should logically include:

Field	Meaning
Error code	Stable machine-readable error identifier.
Message	Safe human-readable summary.
Detail	Optional safe detail for client handling.
Correlation ID	Trace reference for support and audit.
Tenant ID	Tenant context where safe and applicable.
Field errors	Validation errors by field where applicable.
Retryable	Whether retry may be useful.
Documentation reference	Future reference to API documentation where useful.

Error Categories

Category	Meaning
Validation error	Request shape, field value, or business input is invalid.
Authentication error	Caller identity is missing, invalid, or expired.
Authorization error	Caller is authenticated but not allowed to perform the action.
Entitlement error	Subscription, plan, feature, or limit does not allow the action.
Tenant context error	Tenant or organization context is missing, invalid, or unauthorized.
Conflict error	Request conflicts with current business state or version.
Idempotency error	Idempotency key is missing, reused incorrectly, or conflicts with prior request.
Rate or quota error	Request exceeds allowed usage, plan, or operational limits.
Integration error	External dependency failed, timed out, or returned invalid data.
Internal error	Unexpected system failure that must not expose internals.

Error Flow

flowchart LR
    Request[API Request]
    Validation[Validation]
    Security[Security and Entitlement Checks]
    Domain[Domain Rules]
    Error[Standard Error Response]
    Audit[Audit and Correlation]

    Request --> Validation
    Validation -->|invalid| Error
    Validation --> Security
    Security -->|denied| Error
    Security --> Domain
    Domain -->|conflict or rule failure| Error
    Error --> Audit

Error Rules

Rule	Requirement
Errors are stable contracts	Clients should be able to handle errors by code.
Do not leak internals	Stack traces, SQL details, provider secrets, and internal class names must not appear in API errors.
Include correlation	Errors must support supportability and audit through correlation IDs.
Be mobile-friendly	Error payloads must be concise, predictable, and actionable for mobile experiences.
Distinguish retryability	Clients and integrations should know whether retry is appropriate.
Preserve domain language	Business errors should use owning Domain terminology.

Non-Implementation Boundary

This document does not define exact JSON schema, HTTP status mappings, error code catalogue, localization, or exception classes.