Errors, Timeouts, Retries, Cancellation, and Progress

Error taxonomy

• Configuration: Missing environment variable, invalid command, or incompatible version.
• Protocol: Malformed JSON-RPC or unsupported method.
• Validation: Schema mismatch or invalid business value.
• Authorization: Missing identity or permission denied.
• Dependency: Database/API unavailable.
• Timeout/cancellation: The operation deadline has been reached or the caller has stopped the operation.

Retry rules

• Retry only transient failures.
• Use exponential backoff with jitter.
• Respect the overall deadline and server retry hints.
• Do not automatically retry a non-idempotent write unless idempotency protection exists.

Progress and cancellation

A long-running operation can emit progress notifications when negotiated and requested. Cancellation is cooperative: propagate the abort signal to downstream fetch and database operations. Document and audit partial side effects after cancellation.

Useful error message

User-facing text should be safe and actionable: “Order service timed out; try again.” Internal logs can retain the correlation ID, operation, duration, and exception without exposing secrets.