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.

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.

There is no product tier. One ordinary paid seat entitles the whole API surface, Sales Navigator and Recruiter included. Nothing on a seat names a product, no refusal asks you to upgrade a plan, and no field on the error says which tier to buy, because there are no tiers to buy.

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

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.