Error envelopes

Handle failures predictably

Error envelopes define stable FFDBError fields for safe user behavior and operator correlation.

Applications should branch on stable codes and status, not provider text or internal SQLite messages.

Use it for every request boundary, retry policy, UI error state, and support workflow.

Requirements for Error envelopes

• Prerequisite — A client request capable of failing or being aborted.
• Prerequisite — A logging policy that allows request IDs but excludes credentials and signed URLs.
• Required value — Stable code, HTTP status, requestId, bounded details, Retry-After where present, and operation idempotency.
• Required value — A user-safe message and operator escalation path.

FFDBError

• code is the stable machine-readable identifier.
• status is the HTTP status when the request reached the API.
• requestId correlates safe operator logs.
• details contains bounded structured values safe for that public error.

import { FFDBError } from "@ffdb/client";

try {
  await ffdb.query(request);
} catch (error) {
  if (error instanceof FFDBError) {
    console.error(error.code, error.status, error.requestId);
  }
}

Error envelopes workflow

• 1. Catch FFDBError at the request boundary.
• 2. Branch on code/status and distinguish cancellation.
• 3. Honor Retry-After only for retry-safe work.
• 4. Show a safe action to the user.
• 5. Send requestId and bounded context to operators.

Verify error envelopes

Failures produce predictable UI and diagnostics without exposing internal or secret values.

Troubleshoot error envelopes

• Code retries a non-idempotent mutation blindly — stop and reconcile the operation first.
• UI displays raw provider/SQLite text — replace it with stable public messaging.

Continue from Error envelopes

• Add error fixtures to application tests.
• Use Observability to correlate live request IDs.