Errors

Every error response from the Curviate API uses the same flat JSON envelope. Machine-readable codes let your agent handle failures programmatically.

Error envelope

{
  "code": "UNAUTHORIZED",
  "message": "Valid API key required. Use Authorization: Bearer cvt_live_<key>.",
  "retry_hint": null,
  "user_fixable": true,
  "retry_likely_to_succeed": false
}

The error body is a flat JSON object; there is no wrapper "error" key. The top-level properties are code, message, retry_hint, user_fixable, and retry_likely_to_succeed.

Some errors add optional keys. errors (on SEQUENCE_INVALID and MOTION_NOT_STARTABLE) is an array of {path, rule} entries, one per failure. merged_into (on a 404 RESOURCE_NOT_FOUND for a Contact id that was merged into another Contact) is the id that Contact now lives under. reason (on CONTACT_NOT_ENROLLABLE) says why a Contact was not enrolled. feature, required_tier, current_tier and upgrade_url (on TIER_REQUIRED) name the feature, the Tier that includes it, the team's Tier, and for a team Owner where to upgrade. All of these are absent on every other error.

HTTP status codes

422 and 502 are the two statuses integrators most often forget to handle. 422 carries most of the "LinkedIn said no" outcomes, and 502 is where an upstream failure surfaces, not 500.

Error codes

Authentication and request validation

Request validation runs before every entitlement check, so an INVALID_REQUEST says nothing about entitlement. A malformed body is rejected while the seat, the LinkedIn subscription and beta consent are all still unexamined, so a 400 is never evidence that your entitlement is the problem: fix the request and send it again. The reverse is the more useful half, and it is the one worth relying on: a 403 carrying one of the three entitlement codes below proves the request itself parsed and validated cleanly, so there is nothing to fix in the body.

Account state

Reads and retrieval

Entitlement

Three separate refusals, all 403, all user_fixable, and fixed in three different places. Branch on the code, never on the message.

A seat names no LinkedIn product. Any paid seat covers the whole LinkedIn interface, Sales Navigator and Recruiter included. Nothing on a seat names a product, and none of these refusals asks you to buy a different kind of seat. What a Team's subscription buys is its Tier, which covers every one of its seats: read it with GET /v1/billing/tier.

Rate limits

Platform and upstream errors

Account connection (checkpoint)

These codes appear during the account-connect flow (POST /v1/auth/intent, POST /v1/auth/checkpoint/solve).

LinkedIn session errors

Messaging and engagement

Drafts

Contacts

Motions

Billing and seats

Free trial

A brand-new trial customer meets the TRIAL_* codes before almost anything else, so handle TRIAL_EXPIRED and TRIAL_SEAT_LIMIT explicitly if you onboard trial users.

SDK: CurviateError

When using the TypeScript SDK, every API-layer failure throws a CurviateError. The properties are camelCased: code, message, retryHint (with retryHint.delayMs), userFixable, retryLikelyToSucceed, and httpStatus.

import { Curviate, isCurviateError } from "@curviate/sdk";
 
const curviate = new Curviate({ apiKey: process.env.CURVIATE_API_KEY! });
 
try {
  await curviate.accounts.list();
} catch (err) {
  if (!isCurviateError(err)) throw err;
 
  switch (err.code) {
    case "RATE_LIMIT_TENANT":
    case "RATE_LIMIT_ACCOUNT":
      // delayMs is the camelCase view of retry_hint.delay_ms
      await new Promise((r) => setTimeout(r, err.retryHint?.delayMs ?? 60_000));
      break;
    case "UNAUTHORIZED":
      console.error("Check your API key.");
      break;
    case "ACCOUNT_NOT_FOUND":
      console.error("Run accounts.list() and use an id from that response.");
      break;
    default:
      // Required: the taxonomy is additive, so unknown codes will appear.
      console.error(`Unhandled ${err.code} (HTTP ${err.httpStatus}): ${err.message}`);
      throw err;
  }
}

Handling a 429

# A 429 response, rate limit exceeded
HTTP/2 429
Retry-After: 37
ratelimit: "tenant";r=0;t=37
ratelimit-policy: "tenant";q=2500;w=60
Content-Type: application/json
 
{
  "code": "RATE_LIMIT_TENANT",
  "message": "Tenant rate limit exceeded.",
  "retry_hint": { "kind": "delay", "delay_ms": 37000 },
  "user_fixable": false,
  "retry_likely_to_succeed": true
}

Read the wait from Retry-After (seconds) or from retry_hint.delay_ms (milliseconds); they carry the same value in different units. Retry-After is the canonical one, and it is present on every 429.

const res = await fetch(url, { headers: { Authorization: `Bearer ${key}` } });
 
if (res.status === 429) {
  const header = res.headers.get("retry-after");
  const body = await res.json();
  const waitMs =
    (header ? Number(header) * 1000 : undefined) ??
    body.retry_hint?.delay_ms ??
    60_000;
  await new Promise((r) => setTimeout(r, waitMs));
}

Next steps

• Rate limits: the quota formula, the headers, and a worked backoff client.
• Getting started guides: the four calls most integrations start with.
• API reference: the per-endpoint error responses.