Errors

Every error response from the Kwill API has the same JSON shape:

{
  "error": "Invalid or missing API key.",
  "code": "unauthorized"
}

• error — a human-readable description, useful for logs and debugging. Do not parse it programmatically — it can change without notice.
• code — an optional machine-readable code you can branch on in code. Present on well-known error types (see below).

HTTP status codesCopy Anchor Link

Machine-readable error codesCopy Anchor Link

Several code values deserve special handling:

plan_requiredCopy Anchor Link

{
  "error": "API access requires the Studio plan or above.",
  "code": "plan_required",
  "feature": "api",
  "currentPlan": "free",
  "requiredPlan": "studio",
  "upgradeUrl": "https://usekwill.com/settings/billing/upgrade"
}

Your workspace is not on a qualifying plan. Upgrade to Studio or above in Settings → Billing to gain API access.

account_frozenCopy Anchor Link

{
  "error": "Your workspace is frozen. Writes are disabled.",
  "code": "account_frozen"
}

Your workspace has been frozen (typically due to a failed payment). While frozen:

• Reads (GET requests) continue to work normally.
• Writes (POST, PATCH, DELETE) return 403 with this code — except webhook deletions, which are still allowed.
• Webhook events are not emitted; there is no backfill when the workspace is unfrozen.

To unfreeze, resolve the billing issue in Settings → Billing.

Handling errors in codeCopy Anchor Link

const res = await fetch('https://usekwill.com/api/v1/clients', {
  headers: { Authorization: `Bearer ${process.env.KWILL_API_KEY}` },
});

if (!res.ok) {
  const body = await res.json();

  if (body.code === 'plan_required') {
    throw new Error('Upgrade to Studio to use the Kwill API.');
  }
  if (body.code === 'account_frozen') {
    throw new Error('Workspace is frozen — resolve billing to resume writes.');
  }

  throw new Error(`Kwill API error ${res.status}: ${body.error}`);
}