Errors and Debugging

This page describes how errors are surfaced in RowOps, the error classes used, retry behavior, and logging visibility for debugging.

---

Error Classes

Pipeline Errors

Error Class	Stage	Behavior
MaskingFailedError	Mask	Fail-closed; pipeline halts
TransformFailedError	Transform	Fail-closed; pipeline halts
Parse error	Parse	Pipeline halts; no rows returned
Validation error	Validate	Row marked invalid; pipeline continues

Initialization Errors

Error	Cause
Invalid key format	Key does not match expected prefix (pk_ or sk_)
License verification failed	Network error, invalid credentials, or revoked key
Engine initialization failed	Configuration error
Domain not allowed	Publishable key used from unregistered domain

API Errors

Status	Meaning
400	Missing required parameter (e.g., API key)
402	Plan limits exceeded or domain limits exceeded
403	Invalid key, domain not allowed, or not authorized
404	Project or organization not found

---

Error Surfaces

Client-Side Errors

Errors in pipeline execution are thrown as typed exceptions:

try {
  await pipeline.run(data);
} catch (error) {
  if (error instanceof MaskingFailedError) {
    // Handle masking failure
  } else if (error instanceof TransformFailedError) {
    // Handle transform failure
  }
}

Validation Errors

Validation errors are not thrown. They are returned in the result:

const result = await validate(rows, schema);

// Check for invalid rows
if (result.invalid.length > 0) {
  for (const error of result.invalid) {
    console.log(`Row ${error.rowIndex}: ${error.field} - ${error.message}`);
  }
}

API Errors

API endpoints return JSON error responses:

{
  "error": "domain_not_allowed",
  "message": "Domain is not registered for this project"
}

---

Retry Behavior

License Verification

License verification retries on transient failures:

Property	Value
Max retries	3
Backoff	Exponential (100ms, 200ms, 400ms)
Failure behavior	Fail-closed if all retries fail

Webhook Delivery

Webhook delivery retries on server errors:

Property	Value
Max retries	5
Backoff	Exponential (1s, 2s, 4s, 8s, 16s, capped at 60s)
Jitter	20% for thundering herd prevention
No retry on	4xx client errors

Pipeline Operations

Pipeline operations do not automatically retry:

• Parse failures are immediate and fatal
• Mask/Transform failures halt without retry
• Validation completes fully (no partial retry)

---

Logging Visibility

Console Output Prefixes

Client-side logging uses consistent prefixes:

Prefix	Category
[RowOps]	General client initialization and status
[License]	Tier and domain verification issues
[Auth]	Authentication events
[audit]	Audit system status

Audit Logs

Audit logs are persisted server-side:

Property	Behavior
Storage	Server-side database
Failure handling	Fail-safe; errors logged but don't crash application
Missing orgId	Warning logged; no persistence

What Is Logged

Event	Logged Content
Import start	Import ID, schema ID, row count
Import complete	Final status, error count
Key usage	Key ID, domain, timestamp
Configuration changes	Actor, action, entity references

What Is Not Logged

Content	Reason
Row values	Privacy; row data not persisted
Cell content	Privacy; validation errors reference fields, not values
File content	Privacy; parsed data stays client-side

---

Debugging Strategies

Initialization Failures

1. Check console for [RowOps] prefixed messages
2. Verify API key format (pk_ for browser, sk_ for headless)
3. Check network tab for license verification requests
4. Verify domain is registered (publishable keys)

Pipeline Failures

1. Check for thrown MaskingFailedError or TransformFailedError
2. Inspect error message for configuration issues
3. Validate schema configuration before pipeline run
4. Test with smaller dataset to isolate issue

Validation Issues

1. Check result.invalid array for specific errors
2. Review error codes and row indices
3. Compare failing values against schema rules
4. Export invalid rows for offline analysis

Engine Initialization Issues

1. Check console for initialization messages
2. Check browser console for load errors
3. Verify configuration is correct

---

Error Recovery

What the System Recovers From

Scenario	Recovery
Transient network failure (license)	Automatic retry with backoff
Transient webhook failure	Automatic retry with backoff
Invalid rows in dataset	Continue processing; collect errors

What the System Does Not Recover From

Scenario	Behavior
Parse failure	Fatal; no partial results
Masking failure	Fatal; no fallback to unmasked
Transform failure	Fatal; no fallback to untransformed
Engine initialization failure	Pipeline cannot start
All license retries exhausted	Fail-closed