Skip to content

Errors ​

DataSubjectError exposes stable code and httpStatus properties. Branch on code, not the error message. The status is metadata for your host application's error mapping; the error class itself is not a NestJS HTTP exception.

An export() or erase() call can resolve with a failed request. Always inspect the returned request's state, failureReason, and stats.lifecycle; catching rejected promises alone does not establish success.

Configuration and Input ​

CodeHTTP statusMeaning
dsr_invalid_policy500Invalid policy, schema, registry dependencies, or executor configuration
dsr_anonymize_dynamic_replacement500An anonymization replacement is a function; use a supported static scalar
dsr_entity_already_registered500Duplicate entityName registration
dsr_invalid_input400Invalid identifier, option, paged payload/checkpoint, or other API input
dsr_invalid_scope400Tenant scope is absent, incompatible, or does not match the configured single tenant

Policy and registration errors commonly surface during setup. Input and scope checks also run at service and adapter boundaries. A static anonymization replacement can be a string, finite number, or null; other invalid values use dsr_invalid_policy.

Request and Verification ​

CodeHTTP statusMeaning
dsr_request_conflict409Request ID collision, or reuse of a durable request/job key with a different payload
dsr_request_not_found404No matching request or job in the supplied tenant scope
dsr_verification_unavailable400Required stable identities, scoped reads, or verification capabilities are unavailable
dsr_verification_failed500Post-write checks failed for deleted rows, replacement values, or preserved fields

dsr_request_conflict does not mean the service enforces one active request per subject. Durable idempotency is keyed by tenant, request type, and requestKey. Repeating an identical durable call reuses the stored request, including a failed request; changing the payload under that key conflicts.

ErasureVerificationError extends DataSubjectError and carries stats and actions. The service can catch it and preserve sanitized details in the returned request's stats.verification and stats.verificationResidual.

Preview and Recovery ​

CodeHTTP statusMeaning
dsr_plan_mismatch409Invalid preview binding/signature, policy or target-data drift, or a paged job's changed policy
dsr_plan_expired409Signed preview has expired
dsr_durable_execution_required400Missing durable store/key pair, unavailable durable recovery, or preview execution without a transaction-bound setup
dsr_request_persistence_failed500Request persistence or final lookup has an indeterminate outcome; reconcile by request ID
dsr_artifact_write_failed500Artifact preparation or writing failed
dsr_artifact_expired410Durable retry payload or paged artifact has expired or become unavailable
dsr_invalid_state_transition500Recovery or job operation is invalid for the current state
dsr_evidence_report_invalid500Durable evidence/retry payload cannot be safely validated

A fresh preview requires fresh approval and a new request key for a new durable plan. A network retry should reuse the original key and context, including the original preview. Durable execution can record preview failures in a returned failed request rather than throw them.

DataSubjectPersistenceError extends DataSubjectError with requestId, tenantId, dataOutcome, and recovery: 'reconcile_request'. Reconcile that request, the data, and the artifact before executing again. Its dataOutcome describes what the call could establish and may differ from the last persisted record.

After data completion, artifact or notification failure does not mean erasure should run again. With a durable store, retryCompletion(id, tenantId) retries committed artifacts and notifications without repeating entity work. Expired retry payloads cannot be recovered this way. Paged jobs have their own state, checkpoint, and recovery APIs; earlier committed batches remain after a later failure.

Handle Both Failure Channels ​

ts
import {
  DataSubjectError,
  DataSubjectPersistenceError,
  type DataSubjectService,
  type RequestContext,
} from '@nestarc/data-subject';

async function eraseAndInspect(
  service: DataSubjectService,
  subjectId: string,
  tenantId: string,
  context?: RequestContext,
) {
  try {
    const request = await service.erase(subjectId, tenantId, context);
    if (request.state !== 'completed') {
      console.error({
        requestId: request.id,
        state: request.state,
        code: request.failureReason,
        lifecycle: request.stats?.lifecycle,
        verification: request.stats?.verification,
      });
    }
    // Also inspect lifecycle.artifactFailure and notificationFailures.
    return request;
  } catch (error) {
    if (error instanceof DataSubjectPersistenceError) {
      console.error({
        code: error.code,
        requestId: error.requestId,
        tenantId: error.tenantId,
        dataOutcome: error.dataOutcome,
        recovery: error.recovery,
      });
      // Reconcile this ID; do not automatically issue a new erase.
    } else if (error instanceof DataSubjectError) {
      console.error({ code: error.code, httpStatus: error.httpStatus });
    }
    throw error;
  }
}

Check the persistence subclass before the base class. Provider or database exceptions may also escape as other error types, so keep a generic failure path. Public request failure metadata sanitizes unrecognized errors to dsr_operation_failed; that fallback string is not a member of DataSubjectErrorCode.

Separate Error Contracts ​

dsr_subject_not_found (404) and dsr_unregistered_entity (500) remain in the public code object for reserved or adapter-specific use; the core 0.3.0 implementation does not emit them. An empty subject query is not proof that a subject exists or is authorized.

Transcend failures use the separate TranscendIntegrationError class. Its code values are invalid_configuration, invalid_webhook, unauthorized_webhook, unsupported_request, subject_not_mapped, invalid_job, provider_unavailable, and local_execution_incomplete. Inspect its retryable property; these values are not DataSubjectErrorCode members and do not include the transcend_ prefix used in its message. Lint findings likewise use their own dsr_lint_* report codes.

Source: error definitions, service failure handling, durable recovery, paged jobs, and Transcend errors.

Documentation site: MIT License. Check each package for its license.