Request Options — Courier Docs

Timeout

The /slow endpoint takes 3 seconds. Set a shorter timeout to trigger a timeout error.

// Set timeout in milliseconds via .with()
// The /slow endpoint takes 3 seconds — this will timeout
try {
  await caller.misc.with({ timeout: 1000 }).slow()
} catch (error) {
  // HTTPError with timeout message
  console.error("Request timed out")
}

caller.misc.with({ timeout }).slow()SANDBOX

timeout (ms)

idle

// run the request to see the response

Options docs

Retry

Automatically retry failed requests with configurable limits and backoff.

// Use retryMiddleware for automatic retries
import { retryMiddleware } from "@noverax/courier/middleware"

const api = defineApi({
  baseURL: "...",
  middleware: [
    retryMiddleware({
      limit: 3,
      backoff: 300,
      retryOn: (res) => [408, 502, 503, 504].includes(res.status),
    }),
  ],
  groups: { users },
})

Retry is handled via retryMiddleware from @noverax/courier/middleware. It supports exponential backoff and custom retry conditions.

Cache

Control HTTP caching with the standard cache option.

// Next.js cache option (passed through to fetch)
const data = await caller.users.with({
  cache: "force-cache",
}).getAll()

// No caching
const fresh = await caller.users.with({
  cache: "no-store",
}).getAll()

The cache option maps directly to the Fetch API's RequestCache. Use force-cache for aggressive caching or no-store to skip the cache entirely.

Next.js Revalidation

Use Next.js-specific options for ISR-style caching and tag-based revalidation.

// Next.js revalidation — ISR-style caching
const data = await caller.users.with({
  next: { revalidate: 60 },  // revalidate every 60 seconds
}).getAll()

// Tag-based revalidation
const data = await caller.users.with({
  next: { tags: ["users"] },
}).getAll()

// Then in a Server Action:
import { revalidateTag } from "next/cache"
revalidateTag("users")

The next option is passed through to the server-side fetch call. Works with both time-based and tag-based revalidation strategies.

Global Defaults

Set defaults for all requests via createProxyCaller or createProxyQueryCaller.

import { createProxyCaller } from "@noverax/courier"

// Set defaults for all requests
const caller = createProxyCaller<typeof api>("api", {
  timeout: 10000,           // 10s default timeout
  credentials: "include",  // send cookies
  headers: {
    "X-Custom-Header": "value",
  },

  // Global error handler
  onError: (error) => {
    if (error.status === 401) {
      window.location.href = "/login"
    }
  },
})

Global defaults apply to every request made through the instance. Per-request options override globals.