Errors

Handle errors from the Clics TypeScript SDK: status codes, typed failures, and retries for API calls.

Class methods

Methods on clics.projects, clics.goals, clics.funnels, clics.sessions, and clics.stats throw typed errors on HTTP failures (4xx and 5xx). Each error includes a statusCode and structured API error payload when available.

import { Clics } from "@clicsdev/sdk";

const clics = new Clics({ apiKey: process.env.CLICS_API_KEY! });

try {
  await clics.goals.listGoals({ projectId: "proj_xxx" });
} catch (error) {
  if (error instanceof Error && "statusCode" in error) {
    console.error(error.statusCode, error.message);
  }
}

Standalone functions

Imports from @clicsdev/sdk/funcs/* return a Result instead of throwing:

const res = await goalsListGoals(clics, { projectId: "proj_xxx" });

if (!res.ok) {
  console.error(res.error);
  return;
}

console.log(res.value);

Common failures

Status	Meaning	What to do
`400`	Invalid request, such as a missing custom-range boundary or an invalid filter	Check the request shape and use the generated TypeScript types
`401`	Missing, expired, or invalid API key	Create or replace the key in Dashboard
`403`	The key cannot access the resource, or the workspace plan does not expose the endpoint	Confirm workspace access and plan
`404`	The project, goal, funnel, or session does not exist in the selected scope	Re-list the parent resource and use its returned ID
`429`	Too many requests	Retry with exponential backoff and respect any `Retry-After` header
`5xx`	Temporary Clics service error	Retry safe read requests with bounded exponential backoff

Do not retry a mutation (create, update, or delete) blindly unless your own job is idempotent. Log the returned resource ID or retrieve the resource first to avoid accidental duplicates.

API error reference

See Errors for HTTP status codes and response format.