Runtime error codes

Sixb failures have two identities:

• code is stable and intended for programmatic decisions.
• message is written for humans and must not be parsed.

Unknown legacy exceptions use internal.unexpected until their call site receives a specific code.

API errors

HTTP errors expose an optional code while endpoints migrate. The client copies it to SixbApiError.code.

Always tolerate unknown codes: a newer server may introduce one before the client is upgraded.

if (isSixbApiError(error) && error.code === "dataset.not_found") {
  // Recover without depending on the human-readable message.
}

Failure records

Persisted failures and API responses use the same portable record:

interface SixbFailure<TCode extends SixbErrorCode = SixbErrorCode> {
  readonly code: TCode
  readonly message: string
  readonly retryable: boolean
  readonly at: string
  readonly details?: JsonValue
  readonly truncated?: true
}

Messages are safe, bounded summaries owned by Sixb. Native errors, stacks, and causes stay on the private error argument passed to onError; they are never copied into storage or API responses. truncated indicates that optional context exceeded the durable failure size budget.

retryable is the policy attached to the code. It does not override a worker's safety rules; a worker may still refuse to replay work that has already produced side effects.

Contracts by boundary

Each boundary exposes only the codes it can persist.

Additional rules:

• Action failures require { actionId, runId, phase } in details.
• Agent, Pipeline, Sync, and Workflow completion events reuse the failure stored on the run.
• agent.run.finished.error reuses the failure stored on the Agent run.
• Webhook retryability is carried by the persisted failure: retryable outcomes use webhook.delivery_failed; terminal handler responses use webhook.delivery_rejected.
• The outbox retains event.delivery_failed while publication is retried.

Reporting

• context.failure is the same record written to durable storage when one exists.
• error remains the native error for stacks and monitoring integrations.
• Failures without durable storage are normalized once at the reporting boundary.

Normalization

• Coded errors receive their details where they are created.
• Native or out-of-contract errors use one typed capture policy at the boundary.

Error catalog