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 API can return and practical fixes for the most common integration issues.

Error response shape

All error responses return JSON with an "error" string. There is no wrapper envelope on error paths.

{
  "error": "transaction_id is required and must be a string"
}

Error reference

Authentication errors (401)

Endpoints that require a Bearer token: POST /api/v1/track/sale, POST /api/v1/track/refund. The lead endpoint accepts a Bearer token for server mode but does not require it for browser mode.

Validation errors (400)

Track click

Track lead

Track sale

Track refund

Conflict errors (409)

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

Not found errors (404)

Server errors (500)

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.

Troubleshooting

Cookies blocked by the browser

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.

CORS

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 cases

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 handling

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();
  throw new Error(`Affitor error ${response.status}: ${body.error}`);
}

SDK debug: true for verbose logging

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"
// }