fix(audience-core): surface backend-rejected batches as VALIDATION_REJECTED instead of silent drop

Fixes a silent data-loss bug uncovered while wiring the new error
surface. When the backend returned 200 with body { accepted: N, rejected: M }
the queue would clear the entire batch on result.ok and never observe
that M messages were dropped — no callback fired, no metric, no log.

The fix has three parts working together:

1. httpSend now parses the 2xx response body. If it reports rejected > 0,
   httpSend returns ok:false with status:200 and body containing the
   parsed { accepted, rejected } counts. Also fires a new
   `transport_partial_rejected` metric for internal observability.

2. toAudienceError adds a 2xx-with-rejection branch that maps to the new
   AudienceErrorCode 'VALIDATION_REJECTED', with a human-readable
   message ("Backend rejected M of N messages") and the parsed body
   preserved as responseBody.

3. MessageQueue.flush now distinguishes terminal failures from
   retryable ones. On VALIDATION_REJECTED the batch is dropped (the
   backend deterministically rejected those messages — retrying won't
   help) AND onError fires. Generic FLUSH_FAILED / NETWORK_ERROR still
   retain messages for retry on the next flush cycle, as before.

TDD: started with the failing queue test that captures the user-facing
contract (partial-success drops the batch + fires onError). Saw it
fail (queue retained both messages). Implemented the fix across
errors.ts + queue.ts + transport.ts. Added supplemental tests for the
httpSend detection path and the toAudienceError mapping branch.

Tests: 109 core, 47 sdk, 64 pixel. All pass.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ImmutableJeffrey

packages/audience/core/src/errors.test.ts

@@ -95,4 +95,34 @@ describe('toAudienceError', () => {
       expect(err.cause).toBe(networkError.cause);
     });
   });
+
+  describe('partial-rejection (2xx with rejected > 0)', () => {
+    it('maps to VALIDATION_REJECTED with backend body preserved', () => {
+      const partialError: TransportError = {
+        status: 200,
+        endpoint: 'https://api.dev.immutable.com/v1/audience/messages',
+        body: { accepted: 50, rejected: 50 },
+      };
+
+      const err = toAudienceError(partialError, 'flush', 100);
+
+      expect(err.code).toBe('VALIDATION_REJECTED');
+      expect(err.status).toBe(200);
+      expect(err.message).toBe('Backend rejected 50 of 100 messages');
+      expect(err.responseBody).toEqual({ accepted: 50, rejected: 50 });
+    });
+
+    it('handles missing accepted/rejected fields gracefully', () => {
+      const partialError: TransportError = {
+        status: 200,
+        endpoint: 'https://api.dev.immutable.com/v1/audience/messages',
+        body: {},
+      };
+
+      const err = toAudienceError(partialError, 'flush');
+
+      expect(err.code).toBe('VALIDATION_REJECTED');
+      expect(err.message).toBe('Backend rejected 0 of 0 messages');
+    });
+  });
 });

packages/audience/core/src/errors.ts

@@ -63,11 +63,17 @@ export interface TransportResult {
  * - `'CONSENT_SYNC_FAILED'` — PUT to `/v1/audience/tracking-consent` returned non-2xx.
  * - `'NETWORK_ERROR'` — fetch rejected before a response was received
  *                       (network failure, CORS, DNS, etc.).
+ * - `'VALIDATION_REJECTED'` — backend returned 2xx but the body reported
+ *                       `rejected > 0`. Terminal: retrying won't help, the
+ *                       messages were dropped from the queue. Inspect
+ *                       `responseBody` for the per-message detail when the
+ *                       backend provides it.
  */
 export type AudienceErrorCode =
   | 'FLUSH_FAILED'
   | 'CONSENT_SYNC_FAILED'
-  | 'NETWORK_ERROR';
+  | 'NETWORK_ERROR'
+  | 'VALIDATION_REJECTED';
 
 /**
  * Public error type passed to the SDK's `onError` callback. Wraps the
@@ -131,6 +137,7 @@ export function toAudienceError(
   source: 'flush' | 'consent',
   count?: number,
 ): AudienceError {
+  // Network failure — no HTTP response received.
   if (err.status === 0) {
     return new AudienceError({
       code: 'NETWORK_ERROR',
@@ -143,6 +150,23 @@ export function toAudienceError(
     });
   }
 
+  // 2xx response with backend-rejected messages. Terminal, do not retry —
+  // the only way ok:false comes back with a 2xx status is when httpSend
+  // detected `rejected > 0` in the parsed response body.
+  if (err.status >= 200 && err.status < 300) {
+    const body = err.body as { accepted?: number; rejected?: number } | undefined;
+    const rejected = body?.rejected ?? 0;
+    const accepted = body?.accepted ?? 0;
+    return new AudienceError({
+      code: 'VALIDATION_REJECTED',
+      message: `Backend rejected ${rejected} of ${rejected + accepted} messages`,
+      status: err.status,
+      endpoint: err.endpoint,
+      responseBody: err.body,
+    });
+  }
+
+  // Generic HTTP failure (4xx / 5xx).
   return new AudienceError({
     code: source === 'flush' ? 'FLUSH_FAILED' : 'CONSENT_SYNC_FAILED',
     message: source === 'flush'

packages/audience/core/src/queue.test.ts

@@ -265,6 +265,36 @@ describe('MessageQueue', () => {
     expect(onError).toHaveBeenCalled();
   });
 
+  it('drops batch and fires VALIDATION_REJECTED when backend reports partial rejection', async () => {
+    // Backend rejected one message in a batch of two. The 200 OK response
+    // body says { accepted: 1, rejected: 1 }. Expected behaviour:
+    //   - Queue clears the batch (retrying validation failures won't help).
+    //   - onError fires with code 'VALIDATION_REJECTED' so studios are aware.
+    //   - Bug fix: previously the queue checked only result.ok and dropped
+    //     the entire batch silently, losing rejected messages with no signal.
+    const onError = jest.fn();
+    const send = jest.fn<ReturnType<HttpSend>, Parameters<HttpSend>>().mockResolvedValue({
+      ok: false,
+      error: {
+        status: 200,
+        endpoint: 'https://api.immutable.com/v1/audience/messages',
+        body: { accepted: 1, rejected: 1 },
+      },
+    });
+    const queue = createQueue(send, { onError });
+
+    queue.enqueue(makeMessage('1'));
+    queue.enqueue(makeMessage('2'));
+    await queue.flush();
+
+    expect(queue.length).toBe(0);
+    expect(onError).toHaveBeenCalledTimes(1);
+    const err = onError.mock.calls[0][0];
+    expect(err.code).toBe('VALIDATION_REJECTED');
+    expect(err.status).toBe(200);
+    expect(err.responseBody).toEqual({ accepted: 1, rejected: 1 });
+  });
+
   it('purges messages matching a predicate', () => {
     const send = jest.fn<ReturnType<HttpSend>, Parameters<HttpSend>>().mockResolvedValue(okResult);
     const queue = createQueue(send);

packages/audience/core/src/queue.ts

@@ -130,14 +130,26 @@ export class MessageQueue {
       const payload: BatchPayload = { messages: batch };
 
       const result = await this.send(this.endpointUrl, this.publishableKey, payload);
-      if (result.ok) {
+
+      let audienceErr: AudienceError | undefined;
+      if (!result.ok && result.error) {
+        audienceErr = toAudienceError(result.error, 'flush', batch.length);
+      }
+
+      // Drop the batch on success OR on a terminal validation failure.
+      // VALIDATION_REJECTED means the backend deterministically rejected
+      // some messages — retrying won't help, so we drop them rather than
+      // accumulate stale data forever.
+      const isTerminal = audienceErr?.code === 'VALIDATION_REJECTED';
+      if (result.ok || isTerminal) {
         this.messages = this.messages.slice(batch.length);
         this.persist();
       }
+
       this.onFlush?.(result.ok, batch.length);
-      if (!result.ok && result.error && this.onError) {
+      if (audienceErr && this.onError) {
         try {
-          this.onError(toAudienceError(result.error, 'flush', batch.length));
+          this.onError(audienceErr);
         } catch {
           // Swallow callback errors — the queue must not wedge on a throwing handler.
         }

packages/audience/core/src/transport.test.ts

@@ -66,13 +66,45 @@ describe('httpSend', () => {
     }));
   });
 
-  it('returns ok on 2xx response', async () => {
+  it('returns ok on 2xx response with no body', async () => {
     global.fetch = jest.fn().mockResolvedValue({ ok: true });
     const result = await httpSend('https://example.com', 'pk', payload);
     expect(result.ok).toBe(true);
     expect(result.error).toBeUndefined();
   });
 
+  it('returns ok on 2xx response when body reports zero rejected', async () => {
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: { get: () => 'application/json' },
+      json: async () => ({ success: true, accepted: 1, rejected: 0 }),
+    });
+
+    const result = await httpSend('https://example.com', 'pk', payload);
+
+    expect(result.ok).toBe(true);
+    expect(result.error).toBeUndefined();
+  });
+
+  it('returns ok:false with status 200 when backend reports partial rejection', async () => {
+    // The silent-drop bug: backend returns 200 with { accepted: 1, rejected: 1 }
+    // and the queue used to clear the entire batch without surfacing the
+    // rejection. After this fix httpSend treats it as a structured failure.
+    global.fetch = jest.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      headers: { get: () => 'application/json' },
+      json: async () => ({ success: true, accepted: 1, rejected: 1 }),
+    });
+
+    const result = await httpSend('https://example.com', 'pk', payload);
+
+    expect(result.ok).toBe(false);
+    expect(result.error?.status).toBe(200);
+    expect(result.error?.body).toEqual({ success: true, accepted: 1, rejected: 1 });
+  });
+
   it('returns structured error on HTTP failure with parsed JSON body', async () => {
     global.fetch = jest.fn().mockResolvedValue({
       ok: false,

packages/audience/core/src/transport.ts

@@ -67,6 +67,29 @@ export const httpSend: HttpSend = async (
       };
     }
 
+    // Successful HTTP, but the backend MessagesResponse may report
+    // per-message validation failures via { accepted, rejected }. Treat
+    // any rejection as a non-retryable failure so the queue surfaces it
+    // through onError instead of silently dropping the rejected items.
+    const body = await parseBody(response);
+    const bodyObj = (typeof body === 'object' && body !== null)
+      ? body as { accepted?: number; rejected?: number }
+      : undefined;
+    if ((bodyObj?.rejected ?? 0) > 0) {
+      track('audience', 'transport_partial_rejected', {
+        status: response.status,
+        rejected: bodyObj?.rejected ?? 0,
+      });
+      return {
+        ok: false,
+        error: {
+          status: response.status,
+          endpoint: url,
+          body: bodyObj,
+        },
+      };
+    }
+
     return { ok: true };
   } catch (err) {
     const error = new TransportError({