Errors & rate limits

Status codes

Status	Meaning	Retry?
200	Success.	—
400	Malformed request — bad date format, unknown parameter value, invalid body.	No. Fix the request.
401	Missing or invalid API key.	No. Fix the credential.
404	No record with that id or slug.	No.
429	Monthly call limit exceeded.	Not until the allowance resets.
5xx	Server-side fault.	Yes, with backoff.

Rate limiting is monthly, not per-second

This is the part that surprises people. TNL bills a monthly call allowance, not a requests-per-second budget. A 429 means the month's allowance is gone — retrying in a few seconds will not help, and burning retries on a 429 just wastes nothing but your own time, since exhausted calls are already refused.

Read your position from /v1/me:

{
  "usage": {
    "month": "2026-07",
    "calls": 1284,
    "remaining": 8716,
    "monthlyLimit": 10000,
    "resetAt": "2026-08-01T00:00:00.000Z"
  }
}

remaining and monthlyLimit are null on uncapped plans.

Every request counts

Each page of a paginated walk is one call. A 10,000-story backfill at page_size=100 costs 100 calls. Budget before you backfill, and use page_size=100 rather than the default to reduce call count.

Ledger AI Terminal has a separate allowance — 50 questions per month — consumed alongside the normal API call. See Plans & usage.

Handling errors

async function tnlRequest(path, params = {}) {
  const url = `https://theneuralledger.com${path}?${new URLSearchParams(params)}`;

  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await fetch(url, {
      headers: { Authorization: `Bearer ${process.env.TNL_API_KEY}` },
    });

    if (response.ok) return response.json();

    // Do not retry: the request or the credential is wrong, or the
    // monthly allowance is spent. None of these improve by waiting.
    if ([400, 401, 404, 429].includes(response.status)) {
      throw new Error(`TNL API ${response.status}: ${await response.text()}`);
    }

    // 5xx: back off and retry.
    await new Promise((r) => setTimeout(r, 2 ** attempt * 1000));
  }

  throw new Error('TNL API unavailable after 3 attempts');
}

Timeouts

Ledger AI Terminal runs a full investigation and is slow by design — allow up to 180 seconds. The MCP gateway uses the same budget (application 180s, nginx 190s). Ordinary REST reads return promptly; a 30-second client timeout is ample for them, but do not apply that timeout to /v1/ai-terminal.