Errors

A2Error

A2 failures carry an A2Error with a stable code. The session client exposes A2ClientError, which extends A2Error, for server failures and local ones alike, so instanceof A2Error matches both.

// e.g. in a route handler:
import { A2Error } from 'experimental-a2'

export async function POST(req: Request) {
  const { orderId, payload } = await req.json()
  try {
    const events = await ordersServer
      .session(orderId)
      .append({ type: 'created', payload })
    return Response.json(events)
  } catch (err) {
    if (err instanceof A2Error && err.code === 'INVALID_PAYLOAD') {
      // err.details carries the schema issues, in Standard Schema format
      return Response.json({ issues: err.details }, { status: 400 })
    }
    throw err
  }
}

The codes

Retrying an identical batch is not PARTIAL_DUPLICATE_BATCH: it's an idempotent success that returns the previously appended events. A failing handler never makes append throw; handler failures retry and, if persistent, dead-letter the event. See What append never throws for.

A2ClientError

Import A2ClientError from experimental-a2/client. Connection, push, and history read failures, and local A2 validation failures, use this class. Server failures keep their code, message, and details; unexpected thrown values are kept as cause. Invalid API arguments can still throw a native TypeError or RangeError.

• HTTP failures keep status even when they carry a recognized server code.
• A browser WebSocket handshake rejection has no readable HTTP status or body, so it stays CONNECTION_FAILED. A2 never infers an authorization failure or a timeout from an opaque socket error.
• A2 sets no initial connection deadline for HTTP or single-session WebSockets.
• A clean stream end is not an error: the reconnection callback and the connection snapshot carry null.
• Pushes retry STORE_UNAVAILABLE and client transport failures, up to three attempts. No other server code is retried.
• The reconnection policy controls only the live stream. Pausing the stream preserves the writer, but a push can still fail while its WebSocket is unavailable.

NonRetriableError

Throw it (or a subclass, matched by instanceof) from a handler when the failure is deterministic: a guard that refuses this attempt refuses every retry identically. The event dead-letters immediately instead of consuming the ten-failure retry budget. Any other thrown error keeps the ordinary retry contract.

import { z } from 'zod'
import * as a2 from 'experimental-a2'
import { NonRetriableError } from 'experimental-a2'
import { createServer } from 'experimental-a2/server'

const orders = a2.contract({
  name: 'orders',
  events: { created: z.object({ chargeable: z.boolean() }) },
})

export const ordersServer = createServer({
  contract: orders,
  handlers: {
    created: async ({ event }) => {
      if (!event.payload.chargeable) {
        throw new NonRetriableError('this order cannot be charged')
      }
      // transient failures below retry as usual
    },
  },
})

Over the wire

server.fetch owns HTTP serialization. The push route sends an A2Error as:

{ "error": { "code": "INVALID_PAYLOAD", "message": "...", "details": [] } }

with a mapped status:

• Unknown server exceptions become STORE_UNAVAILABLE; their private causes are not sent to clients.
• The session client deserializes the body into an A2ClientError, so client and server code branch on identical server codes.
• Multiplexed WebSocket subscription failures carry the same envelope in their unsubscribed frame, alongside the legacy reason string. Older reason-only frames read as CONNECTION_FAILED.