Errors and retries

Every server API failure has a stable code. Read the code, not the message: messages can change, codes do not. A failure is never a verdict, so never treat it as human, and never run or replay the protected action because verification failed.

#How to read a failure

• /api/v1 endpoints return {"error": "<code>", "code": "<code>"}, with the same value in both fields. A bad_request, not_found, conflict, identity_required or payload_too_large failure also carries message, a sentence saying what to fix, and a 400 that concerns one request field names it in field (for example {"error": "bad_request", "code": "bad_request", "message": "limit must be an integer from 1 to 1000", "field": "limit"}). Log the message and show it to developers; branch only on code. 5xx bodies carry only error and code.
• A 400 bad_request names the request field it refers to in field whenever one field is at fault: a body property (eventId, units, result, approvalToken) or a query parameter (from, to, limit, cursor, view, accountId, series). The same rule holds on every /api/v1 endpoint.
• Paged reads (GET /api/v1/decisions.json, /api/v1/agent-usage.json and /api/v1/usage/ledger) answer page: {limit, total, nextCursor} (the ledger's entries view leaves out total). Follow nextCursor until it is null; a cursor is bound to the period and filters it was issued for, and any other use is 400 with field cursor.
• A 401 unauthorized from /api/v1 also carries hint, which names the credential that was refused, never its value: "server_key" (the Authorization header is missing, does not use the Bearer scheme, or the key is wrong, revoked or past its rotation overlap) or "session_token" (the token is malformed, edited or was not issued by this Telltale server). For example {"error": "unauthorized", "code": "unauthorized", "hint": "server_key"}. A 401 without hint is still unauthorized; read hint when it is there and fall back to checking both. The /v1 endpoints never add it.
• The v1 endpoints of the compatibility API return exactly {"error": "<code>"}.
• 429 responses carry a Retry-After header in seconds. Budgeted responses also carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets); see Rate limits below.
• The browser SDK's own endpoints (/api/sdk) are handled by the SDK. Your code only sees NotAllowedError (collection is paused until consent, or withdrawn), AbortError (superseded work) and errors whose code is network_unavailable (the Telltale server is unreachable, offline or missed the request deadline; client.status() reports ok, degraded or offline and the last error code). optIn() never rejects for network reasons.

#/api/v1 error codes

These apply to POST /api/v1/verify, /api/v1/identify and /api/v1/usage, and to the GET exports.

session_reinit_required has two statuses on /api/v1 because it covers two cases: 401 when the token's session expired, was revoked or was removed, and 409 when POST /api/v1/identify tries to replace an identity already bound to the session. The /v1 compatibility API answers 409 for both (its table is below). The served adapter accepts either status and recovers the same way.

identify and usage never retry automatically, because a repeated write is not always harmless. Usage is idempotent only for an identical eventId with identical facts, which returns the original record with replayed: true. The eventId is looked up before the session token is checked, so this replay also works after the session expired, was withdrawn or was removed. New work still needs a live session token, so report work within the 24-hour session life.

identify checks the account-traits limit before it binds anything: when POST /api/v1/identify answers 409 conflict for accountTraits, the identity was not bound either, and the request can be sent again without accountTraits.

#/v1 error codes (compatibility API)

The compatibility API (/v1) keeps the request and response shapes of the v1 agent-verification API that existing integrations were built on (verify, identify, session lookup and the discovered API export), so such an integration works against Telltale unchanged. New integrations use /api/v1, which also returns reasons, the decision, the policy and attribution and works with the server adapter.

POST /v1/verify, POST /v1/identify, GET /v1/sessions/{sessionId} and GET /v1/discovery/openapi.json use the v1 codes below. Request bodies are closed, so an extra property is a 400. The served adapter calls /api/v1, so this table has no adapter column.

#Session lookup (GET /v1/sessions/{sessionId})

The lookup takes the server key, never a session token. It is a read: retrying it never extends the session or changes its verdict. Every response, errors included, has Cache-Control: no-store.

unknown in a successful answer is a real result: the evidence wasn't enough. A failed lookup is not a verdict.

The adapter still recognises config_unavailable and session_unavailable as retryable, so the same retry policy works against either dialect.

#Errors the adapter raises itself

createTelltaleServer() in /adapters/v1/server.js throws an Error with status and code for every failure above. It also raises these:

#Retry policy

Only verification retries, and only inside one five-second deadline:

1. A valid 503 body with service_unavailable, config_unavailable or session_unavailable is retried, at most three attempts in total, waiting a random 0–250 ms and then 0–500 ms.
2. A 408 or 429 is retried once, only when Retry-After (seconds or an HTTP date) still fits inside the deadline. Without Retry-After it fails.
3. Everything else fails at once: 4xx codes, 500, malformed responses, network errors and timeouts.

The protected application action itself is never retried by Telltale, and your code should not retry it because verification failed. If you call the API without the adapter, follow the same rules. The Server adapters and raw HTTP guide has a fetch example.

#Recover from session_reinit_required

The token is genuine but can no longer be verified. It expired, consent was withdrawn (which revokes it), its session was removed, or it is bound to a different user. Retrying with the same token always fails. A token that is malformed, edited or from another Telltale server is a different failure: 401 unauthorized.

1. On your backend, stop. Do not run the protected action, and answer with a response your page can recognise, for example 409 {"retry": "new_session"}.
2. In the browser, start a fresh session: await client.reset(), identify the current user again from your own authentication, then read a new token with await client.getSessionToken().
3. Send the protected request again once, with the new token. If it fails again, show an error and stop.

async function exportWithRecovery(reportId) {
  for (let attempt = 0; attempt < 2; attempt++) {
    const sessionToken = await client.getSessionToken();
    const response = await fetch('/api/export', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ sessionToken, reportId })
    });
    if (response.status !== 409 || attempt) return response;
    await client.reset();
    await client.identify(await currentIdentity()); // from your own authentication
  }
}

A fresh session starts with little evidence, so its verdict is often unknown at first. Your policy for unknown decides what happens, and unknown is never human. The browser SDK already recovers once by itself when its own collector calls report session_reinit_required, so this loop is only for tokens your backend rejected.

#Browser contexts per session

A session token is reused across page loads for up to 24 hours, and every page start sends evidence under a new browser context. The session keeps per-context bookkeeping for its 100 most recent contexts and forgets the oldest past that; it never refuses evidence or ends the session for the number of contexts, so a person who opens many pages keeps one session, its server-verified identity and its verdict. Older collectors answered 409 session_reinit_required at 100 contexts; the browser SDK still recovers from that by starting a fresh session.

#Session capacity

Each Site keeps at most 100,000 live browser sessions (a session lives 24 hours unless it is revoked; operators can change the cap with TELLTALE_SESSION_CAP). Live sessions are never evicted to make room. At the cap, POST /api/sdk/init answers 503 with code session_capacity_reached and Retry-After; existing sessions keep verifying normally. The browser SDK treats it like any other temporary collector failure: client.status() reports degraded and initialization retries in the background. Other Sites are unaffected.

#Dashboard API codes

The dashboard's own API (/api/admin, /api/auth) answers {"error": "<message>", "code": "<code>"} when a refusal has a stable code. The message is written for people and may be reworded; branch on code. These routes are not part of the server integration contract, but the codes stay stable.

#Warnings on success

A successful verify can still carry a warning. policy_missing means no policy is saved for that actionId, so the default policy decided (Human: allow, AI agent: hold for review, Unknown: allow until you save a rule that holds or denies it, No recent activity: deny). It arrives as warnings: ["policy_missing"] in the /api/v1/verify body and as an Observatory-Warning response header on /api/v1/verify and /v1/verify. Save a policy or fix the actionId; GET /api/v1/integration-status lists the affected actionIds.

#Rate limits

Budgets are counted in memory, per server process, over the window each row names (most are per minute). Each kind of traffic has its own budget, so browser evidence never uses up your backend's verification budget, even when both come from the same address:

A refused sign-in answers the same generic 429 whichever budget was used up.

Every budgeted response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (seconds until the window resets). A 429 also carries Retry-After in seconds. The browser SDK defers its own collector calls until then and never replays application writes. The server adapter retries verification once after a 429 only when Retry-After fits inside its five-second deadline; otherwise the call fails with rate_limited and you fail closed.

Operators can raise the main budgets with TELLTALE_RATE_SERVER_KEY, TELLTALE_RATE_SDK_SESSION, TELLTALE_RATE_SDK_EVENTS, TELLTALE_RATE_INIT_PER_IP, TELLTALE_RATE_INIT_PER_IP_ALL_SITES, TELLTALE_RATE_INIT_PER_SITE and TELLTALE_RATE_IP (whole requests per minute).

#Client addresses behind a reverse proxy

By default the client address is the TCP peer. Behind a reverse proxy every request then shares the proxy's address, which matters only for the per-address budgets above (initialization, failed authentication, invalid tokens). Set TRUST_PROXY=1 (or the number of proxy hops you operate, up to 5) only when every request reaches the Telltale server through proxies you control that append to X-Forwarded-For; the Telltale server then reads the entry that many hops from the right and ignores anything a client wrote further left. TRUST_PROXY is off by default. The public collector origin (Cloudflare Tunnel) uses CF-Connecting-IP as before. TRUST_PROXY does not make a public listener safe: the dashboard listener stays loopback-only.