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, retry_likely_to_succeed, and optionally required_tier and retry_after_ms.

HTTP status codes

Error codes

Every error response carries one of these stable codes. Agent code can use an exhaustive switch statement over error.code without fear of unknown values.

Authentication and request validation

Account state

Subscription and tier gating

Rate limits

Platform errors

Account connection (checkpoint)

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

LinkedIn account errors

These codes appear during the LinkedIn account connection and session lifecycle.

Messaging

Billing

These codes appear on subscription and seat management endpoints.

Generic

SDK: CurviateError

When using the TypeScript SDK, every API-layer failure throws a CurviateError instance. It is the typed equivalent of the REST error envelope — the same code, message, retry_hint, userFixable, retryLikelyToSucceed, requiredTier, and retryAfterMs fields are accessible as class properties.

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)) {
    switch (err.code) {
      case "RATE_LIMIT_TENANT":
        await new Promise((r) => setTimeout(r, err.retryAfterMs ?? 60_000));
        break;
      case "UNAUTHORIZED":
        console.error("Check your API key.");
        break;
      default:
        throw err;
    }
  }
}

Handling errors

# A 429 response — rate limit exceeded
HTTP/2 429
Retry-After: 37
Content-Type: application/json
 
{
  "code": "RATE_LIMIT_TENANT",
  "message": "Tenant rate limit exceeded.",
  "retry_hint": { "kind": "delay", "delayMs": 37000 },
  "user_fixable": false,
  "retry_likely_to_succeed": true,
  "retry_after_ms": 37000
}

The retry_after_ms field (when present) and the Retry-After header both carry the same wait in different units. Use either; Retry-After is the canonical IETF header value in seconds.

See Rate limits for the full client backoff algorithm.