Errors & Troubleshooting

Beta — The Affitor SDKs and CLI are in active development. The documented happy-path works; edge cases may change. Report issues on GitHub.

This page covers every error response the tracking, readiness and CLI endpoints can return, and practical fixes for the most common integration issues.

HTTP status codesCopy Anchor Link

Start from the status code. It tells you whose problem the request is and whether sending it again can help.

Error response shapeCopy Anchor Link

error is always an object, never a plain string. Interpolating body.error straight into a message prints [object Object] — read a field off it.

There are two envelopes. Which one you get depends on what rejected the request, not only on which endpoint you called — the tracking endpoints can return either.

The platform envelopeCopy Anchor Link

Validation, auth, and conflict errors raised by the tracking and CLI endpoints themselves come back like this. Read error.message:

{
  "data": null,
  "error": {
    "status": 400,
    "name": "BadRequestError",
    "message": "transaction_id is required and must be a string",
    "details": {}
  }
}

data is null on every error in this envelope. error.status repeats the HTTP status, and error.name is the error class for that status — BadRequestError (400), UnauthorizedError (401), ForbiddenError (403), NotFoundError (404), ConflictError (409), GoneError (410), InternalServerError (500). error.details is an empty object unless noted below.

Most errors in this envelope carry no stable machine code, so match on the HTTP status and, where you need the specific cause, on the error.message strings listed below. There are two exceptions, both in error.details:

• A suspended account signing in to the CLI gets error.details.code set to ACCOUNT_BLOCKED.
• A CLI 500 carries error.details.request_id — see request IDs.

The typed envelopeCopy Anchor Link

Four things answer with a typed envelope instead. It has no data key, and it carries a stable error.code you can branch on:

{
  "error": {
    "code": "invalid_key",
    "message": "Invalid API token."
  }
}

You get it from:

Only code and message are always present. The rest varies with the case: a rate limit adds status and retry_after_seconds, a retired key adds hint and docs_url, link_disabled adds hint, and a readiness internal_error adds retry_after_seconds.

Handling bothCopy Anchor Link

Read error.code first and fall back to error.message when it is absent:

const body = await response.json();
const detail = body.error?.code
  ? `${body.error.code}: ${body.error.message}`
  : body.error?.message;

Request IDsCopy Anchor Link

Responses from the tracking, readiness and CLI endpoints carry an X-Request-ID header, except GET /api/v1/cli/status: its 200, 401 and 429 have no request ID, and only its 500 does.

On a 500 from a CLI endpoint the same ID is also in the body, both at the end of error.message and in error.details.request_id. Tracking and readiness 500s carry it only in the header.

When you contact support about a failed request, include the X-Request-ID. It is how we find the log line for your request; the error message itself is deliberately generic.

Error referenceCopy Anchor Link

Authentication errors (401)Copy Anchor Link

The rows above apply to the endpoints that require a Bearer token: POST /api/v1/track/sale and POST /api/v1/track/refund.

{
  "data": null,
  "error": {
    "status": 401,
    "name": "UnauthorizedError",
    "message": "Invalid API token",
    "details": {}
  }
}

GET /api/v1/programs/me/readiness fails the same three checks with the typed envelope instead, always with error.code set to invalid_key. Its messages end with a period: Missing or malformed Authorization header. Expected: Bearer <api_token>., Missing API token. and Invalid API token.

The CLI's program-key routes word these differently; see CLI endpoint errors.

POST /api/v1/track/lead accepts a Bearer token for server mode but does not require one, so it answers differently. A missing header — or a header whose token is empty after Bearer — falls back to browser mode: the lead is recorded from the click_id rather than refused. Only a token that matches no program returns 401 there.

The success body is identical in both modes, so a 2xx on its own does not prove your key was read. The one exception is a program configured with lead_auth: server_required, where a browser-mode lead comes back with "provisional": true.

Such a lead settles when your backend sends the server-side lead. A qualifying Stripe payment webhook can also settle it, through the same path the lead endpoint uses, but only when Affitor can resolve the customer from that event — one-off payments through checkout.session.completed, and subscriptions through invoice.payment_succeeded, because subscription checkouts are deliberately left to the invoice event. Send the server-side lead rather than relying on a payment to settle it.

api_key_rotation_requiredCopy Anchor Link

Affitor can mark a specific program API key for mandatory rotation — for example, after the key was exposed outside your control. A marked key keeps authenticating requests until its rotation deadline, so tracking is never interrupted, but every response signals the change so you or your agent can act ahead of time.

Before the deadline, requests with a marked key still succeed and pick up three standard headers:

The JSON body also gains a warnings array. No existing field is removed or renamed.

warnings sits at the top level of the response body. On endpoints that wrap their payload in data, it is a sibling of data, not a field inside it, so read it before you unwrap:

{
  "success": true,
  "warnings": [
    {
      "code": "api_key_rotation_required",
      "message": "This API key must be replaced by 2026-10-03.",
      "hint": "Create a new key in Affitor → Settings → API Key, then update AFFITOR_API_KEY on your server.",
      "rotate_by": "2026-10-03T00:00:00.000Z",
      "docs_url": "https://affitor.com/docs/api-reference/errors#api_key_rotation_required"
    }
  ]
}

After the deadline, the key is retired and every request with it returns:

{
  "error": {
    "code": "api_key_rotation_required",
    "message": "This API key was retired on 2026-10-03.",
    "hint": "Create a new key in Affitor → Settings → API Key.",
    "docs_url": "https://affitor.com/docs/api-reference/errors#api_key_rotation_required"
  }
}

This body is the typed envelope: no data key, and an error.code to branch on.

Fix: In your Affitor dashboard, go to Settings → API Key and regenerate the key, then update AFFITOR_API_KEY on your server with the new value. See Rotate your API key for the full walkthrough.

Validation errors (400)Copy Anchor Link

Track clickCopy Anchor Link

Track leadCopy Anchor Link

Track saleCopy Anchor Link

Track refundCopy Anchor Link

Forbidden errors (403)Copy Anchor Link

This applies to POST /api/v1/track/click and POST /api/v1/track/lead in test mode only. A browser-mode test event with no key is not checked this way.

{
  "data": null,
  "error": {
    "status": 403,
    "name": "ForbiddenError",
    "message": "program_id does not match the API key",
    "details": {}
  }
}

Conflict errors (409)Copy Anchor Link

Duplicate detection is keyed on processor_event_id (mapped from transaction_id). The check is scoped globally, not per-program.

Not found errors (404)Copy Anchor Link

Rate limits (429)Copy Anchor Link

Every /api/v1/ endpoint below is rate limited per minute. The click and lead endpoints are bucketed by client IP, because they are called without a key; the rest are bucketed by API key, falling back to IP when no key is sent.

Every response on these routes carries the current budget, not just the ones that are refused:

Over the limit, the request is refused with the typed envelope — no data key:

{
  "error": {
    "status": 429,
    "code": "rate_limited",
    "message": "Too many requests.",
    "retry_after_seconds": 42
  }
}

Wait retry_after_seconds (or read Retry-After) before retrying. The request is refused before it reaches the endpoint, so nothing was recorded and the retry is safe.

The synthetic verification chain has a second, separate cap of 10 runs per program per hour. It reports the same rate_limited code on POST /api/v1/cli/test-event, with its own retry_after_seconds. That one is checked inside the endpoint rather than in front of it, so the "nothing was recorded" guarantee above does not carry over: the chain's test fixture is prepared before the cap is consulted. No chain runs, but the fixture records for your program may have been created or refreshed.

Server errors (500)Copy Anchor Link

A 500 means the request failed on our side. The message is deliberately generic — the detail goes to our logs under the response's X-Request-ID, so include that ID when you contact support.

{
  "data": null,
  "error": {
    "status": 500,
    "name": "InternalServerError",
    "message": "Sale tracking failed",
    "details": {}
  }
}

The readiness 500 uses the typed envelope:

{
  "error": {
    "code": "internal_error",
    "message": "Failed to compute readiness. Retry shortly.",
    "retry_after_seconds": 10
  }
}

Metric update failures (step 10 in the sale flow) are logged as warnings and do not cause a 500 — the sale and commission are still created.

For 500s from the CLI endpoints, see CLI endpoint errors.

CLI endpoint errorsCopy Anchor Link

The Affitor CLI talks to the /api/v1/cli/* endpoints. They answer in the platform envelope, except the rate limits and a retired key, which use the typed one. This section is about what the API returns; for the codes the CLI itself prints with --json, see CLI commands.

The routes authenticate in two different ways, and the fix for a 401 depends on which:

• Account session — init and programs take the login token from affitor login. Fix a 401 by logging in again. Regenerating a program key does not help.
• Program API key — status and test-event take the program's API key. Fix a 401 as in authentication errors.

Login (/api/v1/cli/auth/*)Copy Anchor Link

These routes run the browser login that affitor login starts. They take no credential.

An expired session is not an error on /auth/poll: it answers 200 with "data": { "status": "expired" }.

ACCOUNT_BLOCKEDCopy Anchor Link

POST /api/v1/cli/auth/callback refuses to log in a suspended account. It is the one platform-envelope error with a stable code, in error.details.code:

{
  "data": null,
  "error": {
    "status": 403,
    "name": "ForbiddenError",
    "message": "Your account has been suspended.",
    "details": {
      "code": "ACCOUNT_BLOCKED"
    }
  }
}

Cause: the Affitor account you signed in with is suspended. Fix: retrying or signing in again will not help. Contact Affitor support.

Account-session routes (init, programs)Copy Anchor Link

Program-key routes (status, test-event)Copy Anchor Link

Retired endpointCopy Anchor Link

A CLI 500 puts the request ID in the message and in details:

{
  "data": null,
  "error": {
    "status": 500,
    "name": "InternalServerError",
    "message": "Failed to get status (request_id: 9f2c4e1a7b3d5f60a8c2e4b6d8f0a1c3)",
    "details": {
      "request_id": "9f2c4e1a7b3d5f60a8c2e4b6d8f0a1c3"
    }
  }
}

TroubleshootingCopy Anchor Link

Cookies blocked by the browserCopy Anchor Link

The Affitor browser SDK stores the click ID in a first-party cookie named affitor_click_id (SameSite=Lax; Secure on HTTPS). Attribution is lost when:

• The user has a browser extension or privacy setting that blocks first-party cookies.
• The page is served over HTTP in production (the Secure flag is only set on HTTPS).
• Safari ITP aggressively expires cookies set via JavaScript within 7 days for domains classified as trackers.

Fix: The SDK auto-detects the root domain and sets the cookie there (e.g. .example.com) to share attribution across subdomains. For custom domains or cross-domain attribution, pass cookieDomain explicitly:

init({ programId: 123, cookieDomain: '.example.com' });

There is no server-side fallback for blocked cookies — if the cookie is missing when signup() fires, pass customer_key alone and accept that the lead will be unattributed.

CORSCopy Anchor Link

The tracking API (api.affitor.com) must allow your site's origin for browser-mode requests. If you see CORS errors:

1. Check that your site's domain is listed in the allowed origins on the Affitor program settings page.
2. Browser-mode tracking calls (/track/click, /track/lead without a Bearer token) are the only routes intended for direct browser fetch. Server-mode routes (/track/sale, /track/refund) should only be called from your backend — they do not need CORS.
3. In development, use localhost explicitly rather than 127.0.0.1 (or vice versa) — the two are treated as different origins.

Attribution window edge casesCopy Anchor Link

The attribution window defaults to 60 days and is set per program (cookie_window_days). The actual value is returned in the click response:

{
  "success": true,
  "click_id": "cust_42_1712345678901",
  "cookie_window_days": 60
}

The SDK applies this value as the cookie expiry. Edge cases:

Duplicate transaction_id handlingCopy Anchor Link

The sale endpoint uses transaction_id as a globally unique idempotency key stored as processor_event_id. The rules:

• Sending the same transaction_id twice returns 409 Conflict — the second request is a no-op.
• The 409 is not an error to retry. Your integration should treat it as "already recorded" and proceed.
• Test-mode sales use test_txn_<timestamp> when transaction_id is omitted, so test records are never duplicates unless you pass the same value explicitly.
• If a sale was recorded but commission creation failed (500), the transaction_id is still consumed. Contact Affitor support to investigate the commission state before re-submitting under a new ID.

Recommended pattern:

const response = await fetch('https://api.affitor.com/api/v1/track/sale', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${PROGRAM_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ transaction_id: chargeId, ... }),
});

if (response.status === 409) {
  // Already recorded — safe to continue
  return;
}

if (!response.ok) {
  // Unexpected error — log and alert
  const body = await response.json();
  // `error` is always an object. `code` is present only on the typed envelope
  // (rate_limited on a 429, api_key_rotation_required on a retired key);
  // the platform envelope carries a message and no code.
  const detail = body.error?.code
    ? `${body.error.code}: ${body.error.message}`
    : body.error?.message;
  throw new Error(`Affitor error ${response.status}: ${detail}`);
}

SDK debug: true for verbose loggingCopy Anchor Link

Pass debug: true to init() to enable verbose console output. This sets AffitorInitOptions.debug on the tracker instance.

import { init } from '@affitor/sdk';

init({
  programId: 123,
  debug: true,
});

With debug: true, the SDK logs to the browser console using [Affitor] as the prefix for every info and warn level message — including initialization, program ID resolution, click tracking, and signup calls. Errors (console.error) are always logged regardless of the debug flag.

[Affitor] Affitor SDK initialized: { programId: 123, debug: true }
[Affitor] Using program ID: 123
[Affitor] Click tracked, click_id saved: cust_42_1712345678901
[Affitor] Signup tracked successfully

Disable in production. The debug flag is intended for development and integration testing only. Leave it off in production builds to avoid leaking internal state to end users.

To check the current tracker state at any point:

import { getData } from '@affitor/sdk';

console.log(getData());
// {
//   clickId: "cust_42_1712345678901",
//   programId: 123,
//   hasAttribution: true,
//   affiliateUrl: "https://example.com/?aff=abc123"
// }