Error codes

HTTP error codes returned by the token signing handler and the widget session API.

Token signing handler errors

createUnchurnHandler returns these HTTP responses. Source: packages/widget/src/nextjs.ts.

All error bodies are empty — no information is leaked to the browser. Errors are logged server-side.

resolveUser shape validation:

If resolveUser returns a value where:

• subscriptionId is not a non-empty string → 500
• mode is not 'test', 'live', or undefined → 500
• subscriptionId contains characters outside [A-Za-z0-9_-] → 500 (detected at mint time by assertValidIdentifier)

Widget session API errors

The Unchurn backend returns structured errors for widget requests. Source: packages/contracts/src/errors.ts.

Error response shape

// packages/contracts/src/errors.ts
export const apiErrorResponseSchema = z.object({
  error: z.object({
    code: apiErrorCodeSchema,
    message: z.string(),
    docs: z.string().url().optional(),
    example_file: z.string().optional(),
    offer_kind: offerKindSchema.optional(),
  }),
});

Error codes

useUnchurn error state

The hook’s error field is an Error | null. It reflects:

• Token endpoint returned a non-2xx status: Error('Token endpoint returned HTTP <status>')
• Token endpoint returned a malformed response body: a Zod validation error describing which field was wrong

These surface as the hook’s error field (not thrown), so the merchant can show a degraded UI instead of crashing.

Cross-links

• Widget API — createUnchurnHandler — handler that emits 401/405/500
• Widget API — useUnchurn — hook error field
• Supported subscriptions — eligibility constraints that surface as 409 / 422