API errors and rate limits

Every failure from /api/v1 is the same JSON shape with a stable machine-readable code. Branch on code, not on the message text or the HTTP status alone — messages get reworded, codes never change meaning.

{
  "error": {
    "code": "not_entitled",
    "message": "This isn't part of your purchases. Buy the pack or lifetime access to download it.",
    "request_id": "5f3c9a10-2d6b-4b2e-9f77-1c0a8de41b52"
  }
}

request_id is always populated, and always equals the x-request-id header on the same response — so you can log it from the headers of successful calls too. If you send your own x-request-id (8–64 characters, letters, digits, _ and -), we use yours instead of generating one. Log it either way: quoting it in a support email points us straight at the call that failed.

Error codes

invalid_api_key deliberately does not distinguish "malformed" from "no such key", api_disabled does not say which switch produced it, and blocked says nothing at all. That is a security choice, not an omission.

Rate limits

Limits are per key for authenticated calls, so one busy script of yours cannot starve another — and a colleague behind the same office IP never pays for your loop. The public catalog is limited per IP address instead, since there is no key to attribute it to.

Reads and downloads have separate budgets, so listing your library never eats into your download allowance. Downloads are the tight one — each streams a multi-megabyte file — so pull sequentially rather than in parallel.

Rate-limit headers

Every response that reached the rate limiter carries them — successes, 404s, 403 not_entitled, and the 429 itself — so a well-behaved client can pace itself long before it sees a 429. The exceptions are the refusals decided before the limiter runs: blocked, a 500 internal_error, and (on the authenticated routes) api_disabled and not_eligible come back without them. Both spellings go out; use whichever your HTTP client already parses.

RateLimit-Policy: "download";q=30;w=60
RateLimit: "download";r=27;t=41
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
X-RateLimit-Reset: 41

Policy names you will see: read, download, public, auth.

A 429 additionally carries Retry-After, in seconds:

HTTP/1.1 429 Too Many Requests
Retry-After: 41

Backing off politely

fetch() {
  for attempt in 1 2 3 4 5; do
    code=$(curl -s -o body.json -w '%{http_code}' \
      -D headers.txt -H "Authorization: Bearer $TJA_API_KEY" "$1")
    [ "$code" = "429" ] || { cat body.json; return 0; }
    wait=$(awk 'tolower($1) == "retry-after:" { print $2 }' headers.txt | tr -d '\r')
    sleep "${wait:-5}"
  done
  echo "gave up on $1" >&2
  return 1
}

Two rules that keep you comfortably inside the limits:

• Honour Retry-After. It is exact; guessing is not.
• Watch X-RateLimit-Remaining and slow down before it reaches zero, rather than sprinting into a 429 and recovering.

Repeated failed authentication is limited separately and by IP. If you are looping on invalid_api_key, fix the key rather than retrying — you will hit the failed-auth limit and then get 429s that look unrelated.

Troubleshooting

• 401 on every call — check the header name and that the key was copied whole, including the trailing checksum. Try /v1/me first; it is the cheapest test.
• 403 insufficient_scope on downloads only — the key was created without downloads:read. Scopes cannot be edited; create a new key.
• 404 on a pack you own — coming-soon packs are not downloadable yet, and archived ones are gone. Confirm the slug against /v1/packs.
• A download that redirects to a sign-in page — you fetched preview_url (the public preview GLB) instead of download_url, without a key. See API endpoint reference.
• amount is null in /v1/orders — an older order never recorded a total. That means unknown, not free.

Next steps

• API authentication and keys
• API endpoint reference
• API quickstart