fix(enrichments): project provider failures (#6917)

* fix(enrichments): project provider failures

* fix(enrichments): share Prospeo failure projection

Author: TheodoreSpeaks

apps/sim/enrichments/index.ts

@@ -4,6 +4,8 @@ export type {
   EnrichmentInputField,
   EnrichmentOutputField,
   EnrichmentProvider,
+  EnrichmentProviderFailure,
+  EnrichmentProviderFailureProjection,
   EnrichmentRegistry,
   EnrichmentRunContext,
 } from './types'

apps/sim/enrichments/phone-number/phone-number.test.ts

@@ -76,6 +76,27 @@ describe('phone-number enrichment cascade', () => {
       expect(p.buildParams({ fullName: 'John Doe' })).toBeNull()
       expect(p.mapOutput({ person: { mobile: { mobile: '+1555' } } })).toEqual({ phone: '+1555' })
     })
+
+    it('recognizes only Prospeo NO_MATCH as a clean miss', () => {
+      expect(
+        p.projectFailure({
+          error: 'NO_MATCH',
+          output: { status: 400, data: { error: true, error_code: 'NO_MATCH' } },
+        })
+      ).toEqual({ status: 'no_match' })
+      expect(
+        p.projectFailure({
+          error: 'INVALID_API_KEY',
+          output: { status: 400, data: { error: true, error_code: 'INVALID_API_KEY' } },
+        })
+      ).toEqual({ status: 'error', error: 'INVALID_API_KEY' })
+      expect(
+        p.projectFailure({
+          error: 'Bad Request',
+          output: { status: 400, data: { error: true } },
+        })
+      ).toEqual({ status: 'error', error: 'Bad Request' })
+    })
   })
 
   describe('leadmagic', () => {

apps/sim/enrichments/phone-number/phone-number.ts

@@ -1,5 +1,6 @@
 import { Phone } from '@sim/emcn/icons'
 import { filterUndefined } from '@sim/utils/object'
+import { projectProspeoEnrichmentFailure } from '@/enrichments/provider-failures/prospeo'
 import { firstNonEmpty, normalizeDomain, str, toolProvider } from '@/enrichments/providers'
 import type { EnrichmentConfig } from '@/enrichments/types'
 
@@ -103,6 +104,7 @@ export const phoneNumberEnrichment: EnrichmentConfig = {
           enrich_mobile: true,
         })
       },
+      projectFailure: projectProspeoEnrichmentFailure,
       mapOutput: (output) => {
         const person = output.person as Record<string, unknown> | undefined
         const mobile = person?.mobile as Record<string, unknown> | undefined

apps/sim/enrichments/provider-failures/prospeo.ts

@@ -0,0 +1,20 @@
+import { isRecordLike } from '@sim/utils/object'
+import { projectEnrichmentProviderFailure } from '@/enrichments/providers'
+import type {
+  EnrichmentProviderFailure,
+  EnrichmentProviderFailureProjection,
+} from '@/enrichments/types'
+
+/** Projects Prospeo's documented `NO_MATCH` error as a clean provider miss. */
+export function projectProspeoEnrichmentFailure(
+  failure: EnrichmentProviderFailure
+): EnrichmentProviderFailureProjection {
+  if (
+    isRecordLike(failure.output) &&
+    isRecordLike(failure.output.data) &&
+    failure.output.data.error_code === 'NO_MATCH'
+  ) {
+    return { status: 'no_match' }
+  }
+  return projectEnrichmentProviderFailure(failure)
+}

apps/sim/enrichments/providers.ts

@@ -1,7 +1,10 @@
+import { isRecordLike } from '@sim/utils/object'
 import type {
   EnrichmentInputField,
   EnrichmentOutputField,
   EnrichmentProvider,
+  EnrichmentProviderFailure,
+  EnrichmentProviderFailureProjection,
 } from '@/enrichments/types'
 
 /**
@@ -56,13 +59,30 @@ export function splitName(fullName: unknown): { firstName: string; lastName: str
   return { firstName: parts[0], lastName: parts.slice(1).join(' ') }
 }
 
+/** Projects the standard provider failure contract into a cascade outcome. */
+export function projectEnrichmentProviderFailure(
+  failure: EnrichmentProviderFailure
+): EnrichmentProviderFailureProjection {
+  if (isRecordLike(failure.output) && failure.output.status === 404) {
+    return { status: 'no_match' }
+  }
+  return { status: 'error', error: failure.error }
+}
+
+type EnrichmentProviderDefinition = Omit<EnrichmentProvider, 'projectFailure'> & {
+  projectFailure?: EnrichmentProvider['projectFailure']
+}
+
 /**
  * Declares a tool-backed enrichment provider as plain data. Keeping this free of
  * any `@/tools` reference (the cascade runner does the `executeTool` call) means
  * the enrichment catalog stays client-safe — the table UI imports it only for
  * metadata. Workspace scope and BYOK / hosted-key injection are handled by the
  * runner when it executes `toolId`.
  */
-export function toolProvider(provider: EnrichmentProvider): EnrichmentProvider {
-  return provider
+export function toolProvider(provider: EnrichmentProviderDefinition): EnrichmentProvider {
+  return {
+    ...provider,
+    projectFailure: provider.projectFailure ?? projectEnrichmentProviderFailure,
+  }
 }

apps/sim/enrichments/run.test.ts

@@ -6,6 +6,7 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 const { mockExecuteTool } = vi.hoisted(() => ({ mockExecuteTool: vi.fn() }))
 vi.mock('@/tools', () => ({ executeTool: mockExecuteTool }))
 
+import { projectEnrichmentProviderFailure, toolProvider } from '@/enrichments/providers'
 import { runEnrichment, skippedEnrichmentDetail } from '@/enrichments/run'
 import type { EnrichmentConfig, EnrichmentProvider } from '@/enrichments/types'
 import { ResolvedSecretTraceRegistry } from '@/executor/utils/resolved-secret-trace-registry'
@@ -16,16 +17,18 @@ function prov(
   id: string,
   opts: {
     build?: (inputs: Record<string, unknown>) => Record<string, unknown> | null
+    projectFailure?: EnrichmentProvider['projectFailure']
     map?: (output: Record<string, unknown>) => Record<string, unknown> | null
   } = {}
 ): EnrichmentProvider {
-  return {
+  return toolProvider({
     id,
     label: id.toUpperCase(),
     toolId: `tool_${id}`,
     buildParams: opts.build ?? (() => ({ q: 'x' })),
+    projectFailure: opts.projectFailure,
     mapOutput: opts.map ?? ((o) => (o.email ? { email: o.email } : null)),
-  }
+  })
 }
 
 function config(providers: EnrichmentProvider[]): EnrichmentConfig {
@@ -138,6 +141,82 @@ describe('runEnrichment cascade detail', () => {
     expect(outcome.detail.providers.map((p) => p.status)).toEqual(['no_match'])
   })
 
+  it('continues after a provider translates a documented error into a clean miss', async () => {
+    mockExecuteTool.mockImplementation((toolId: string) => {
+      if (toolId === 'tool_a') {
+        return {
+          success: false,
+          error: 'NO_MATCH',
+          output: { status: 400, data: { error: true, error_code: 'NO_MATCH' } },
+        }
+      }
+      return { success: true, output: { email: 'j@acme.com' } }
+    })
+
+    const outcome = await runEnrichment(
+      config([
+        prov('a', {
+          projectFailure: (failure) => {
+            if (
+              typeof failure.output === 'object' &&
+              failure.output !== null &&
+              'data' in failure.output &&
+              typeof failure.output.data === 'object' &&
+              failure.output.data !== null &&
+              'error_code' in failure.output.data &&
+              failure.output.data.error_code === 'NO_MATCH'
+            ) {
+              return { status: 'no_match' }
+            }
+            return projectEnrichmentProviderFailure(failure)
+          },
+        }),
+        prov('b'),
+      ]),
+      {},
+      ctx
+    )
+
+    expect(outcome.result).toEqual({ email: 'j@acme.com' })
+    expect(outcome.error).toBeNull()
+    expect(outcome.detail.providers.map((p) => p.status)).toEqual(['no_match', 'matched'])
+    expect(mockExecuteTool).toHaveBeenCalledTimes(2)
+  })
+
+  it('keeps non-miss provider errors as errors', async () => {
+    mockExecuteTool.mockResolvedValue({
+      success: false,
+      error: 'INVALID_API_KEY',
+      output: { status: 400, data: { error: true, error_code: 'INVALID_API_KEY' } },
+    })
+
+    const outcome = await runEnrichment(
+      config([
+        prov('a', {
+          projectFailure: (failure) => {
+            if (
+              typeof failure.output === 'object' &&
+              failure.output !== null &&
+              'data' in failure.output &&
+              typeof failure.output.data === 'object' &&
+              failure.output.data !== null &&
+              'error_code' in failure.output.data &&
+              failure.output.data.error_code === 'NO_MATCH'
+            ) {
+              return { status: 'no_match' }
+            }
+            return projectEnrichmentProviderFailure(failure)
+          },
+        }),
+      ]),
+      {},
+      ctx
+    )
+
+    expect(outcome.error).toBe('INVALID_API_KEY')
+    expect(outcome.detail.providers.map((p) => p.status)).toEqual(['error'])
+  })
+
   it('skippedEnrichmentDetail marks every provider skipped without running', () => {
     const detail = skippedEnrichmentDetail(config([prov('a'), prov('b')]))
     expect(detail.matchedProvider).toBeNull()

apps/sim/enrichments/run.ts

@@ -119,13 +119,11 @@ export async function runEnrichment(
         }
       )
       if (!response.success) {
-        // A 404 means the provider simply has no record for these inputs — a
-        // clean no-match, not an infra failure. Fall through to the next
-        // provider without counting it as an error (so the cell shows "Not
-        // found" rather than an error). Other statuses (auth, rate-limit, 5xx)
-        // are real errors and propagate.
-        const status = (response.output as { status?: unknown } | undefined)?.status
-        if (status === 404) {
+        const projection = provider.projectFailure({
+          error: response.error ?? `${provider.toolId} failed`,
+          output: response.output,
+        })
+        if (projection.status === 'no_match') {
           providers.push({
             id: provider.id,
             label: provider.label,
@@ -137,7 +135,7 @@ export async function runEnrichment(
           })
           continue
         }
-        throw new Error(response.error ?? `${provider.toolId} failed`)
+        throw new Error(projection.error)
       }
       const providerCost = readCost(response.output)
       cost += providerCost

apps/sim/enrichments/types.ts

@@ -36,6 +36,17 @@ export interface EnrichmentRunContext {
   resolvedSecretTraceRegistry?: ResolvedSecretTraceRegistry
 }
 
+/** Failed tool result projected into the enrichment provider boundary. */
+export interface EnrichmentProviderFailure {
+  error: string
+  output: unknown
+}
+
+/** Normalized result of projecting a failed provider tool call. */
+export type EnrichmentProviderFailureProjection =
+  | { status: 'no_match' }
+  | { status: 'error'; error: string }
+
 /**
  * One data source an enrichment can try, described as plain data so the catalog
  * (which the table UI imports for metadata) never pulls in server-only tool
@@ -55,6 +66,11 @@ export interface EnrichmentProvider {
    * inputs to run this provider (cascade falls through to the next).
    */
   buildParams: (inputs: Record<string, unknown>) => Record<string, unknown> | null
+  /**
+   * Projects a failed tool call into the provider-neutral cascade outcome.
+   * `toolProvider` supplies the standard HTTP projection unless overridden.
+   */
+  projectFailure: (failure: EnrichmentProviderFailure) => EnrichmentProviderFailureProjection
   /**
    * Maps the tool's output to `{ [outputId]: value }`, or `null` for no result.
    * An empty/`null` result falls through to the next provider.

apps/sim/enrichments/work-email/work-email.test.ts

@@ -68,6 +68,21 @@ describe('work-email enrichment cascade', () => {
         email: 'j@acme.com',
       })
     })
+
+    it('projects Prospeo NO_MATCH as a clean miss without hiding genuine errors', () => {
+      expect(
+        p.projectFailure({
+          error: 'NO_MATCH',
+          output: { status: 400, data: { error: true, error_code: 'NO_MATCH' } },
+        })
+      ).toEqual({ status: 'no_match' })
+      expect(
+        p.projectFailure({
+          error: 'INVALID_API_KEY',
+          output: { status: 400, data: { error: true, error_code: 'INVALID_API_KEY' } },
+        })
+      ).toEqual({ status: 'error', error: 'INVALID_API_KEY' })
+    })
   })
 
   describe('wiza (opportunistic)', () => {

apps/sim/enrichments/work-email/work-email.ts

@@ -1,5 +1,6 @@
 import { Mail } from '@sim/emcn/icons'
 import { filterUndefined } from '@sim/utils/object'
+import { projectProspeoEnrichmentFailure } from '@/enrichments/provider-failures/prospeo'
 import { normalizeDomain, splitName, str, toolProvider } from '@/enrichments/providers'
 import type { EnrichmentConfig } from '@/enrichments/types'
 
@@ -86,6 +87,7 @@ export const workEmailEnrichment: EnrichmentConfig = {
           company_website: companyWebsite || undefined,
         })
       },
+      projectFailure: projectProspeoEnrichmentFailure,
       mapOutput: (output) => {
         const person = output.person as Record<string, unknown> | undefined
         const emailObj = person?.email as Record<string, unknown> | undefined