Error Types
Public error models
IngestX explicitly separates row level validation failures (which are collected gracefully) from fatal ingestion errors (which destroy the process entirely).
Fatal Ingestion Errors
If a fatal error occurs, the result.status transitions to failed, and result.error is populated with an implementation of the IngestionError interface.
export interface IngestionError {
type: IngestionErrorType;
message: string;
details?: unknown;
cause?: unknown; // The underlying caught Error object
}IngestionErrorType
HEADER_MISMATCH: The spreadsheet headers structurally failed to map to yourColumnConfig.COLLECTION_LIMIT_EXCEEDED: You exceeded themaxCollectedRowsconfigured limit.INGESTION_ERROR: General parser failure (e.g. invalid zip archive for Excel, or file unreadable).
HeaderMismatchError
If a mismatch occurs, the error type is narrowed. It explicitly lists the required keys it expected to find, the keys that were missing in the spreadsheet, and the unmapped headers it encountered.
export interface HeaderMismatchError extends IngestionError {
type: IngestionErrorType.HEADER_MISMATCH;
details: {
expected: string[];
missing: string[];
unexpected: string[];
};
}Row level Validation Errors
Row validation failures do not trigger an IngestionError. They are expected parts of processing messy spreadsheets.
Instead, when a row fails validation, the final payload pushes the detailed failure into errorsData.rowWiseErrors.
type RowValidationError = {
rowIndex: number;
columnKey: string;
receivedValue: unknown;
errorMessage: string; // From ix schema e.g. "Name too short"
};