Troubleshooting

The key is missing or not being sent the way the API expects. Send it as a bearer token: Authorization: Bearer tl_live_xxx. A common mistake is sending the key as a raw header value without the Bearer prefix, or pasting a key that was truncated on copy. Confirm the key still exists and is enabled in Settings → API Keys.

The key is authenticated but lacks the scope the endpoint requires. The message names the missing scope. For example, creating a geofence needs manage:geofences, not just read:geofences. Scopes are fixed at key creation—mint a new key with the scope you need rather than trying to edit an existing one. See Authentication.

The API is not enabled for the workspace yet. Creating any API key from Settings → API Keys enables it automatically—create one and retry.

They are distinct on purpose. 401 means we could not authenticate the key at all. 403 means the key is valid but not allowed to do this (wrong scope, or API not enabled). 404 means the resource does not exist or is not visible to this key—which is also what a tag outside the key's allow-list looks like (see below).

The key is probably restricted to a tag allow-list that does not include this tag. A scoped key only ever sees the tags it was granted; any other tag id resolves to not_found, by design, so a restricted key cannot probe for tags it shouldn't know about. Either use a key whose scope covers the tag, or add the tag to the key's allow-list when you create a replacement key.

If the key is scoped to an allow-list, the list endpoint only returns the tags in that list (and skips any that no longer exist). This is expected. A key scoped to all tags returns the full workspace set, page by page.

This is correct behavior, not a bug. Pages can be under-full when the window straddles gaps (for example, a scoped tag that was deleted). The rule is simple: keep paging until nextCursor is null. Never stop early just because a page looks short.

Same rule applies. An empty page does not mean you have reached the end—only a null nextCursor means that. Pass the returned cursor to the next request and continue.

Cursors are opaque. If you hand-build, truncate, or otherwise corrupt a cursor, it is treated as absent and the list starts over from the first page rather than erroring. Always pass back the exact nextCursor string you received, unmodified, and do not try to parse or construct cursors yourself.

Delivery URLs must be public HTTPS endpoints. We reject anything that is not https://, that embeds credentials (https://user:pass@host), or that points at a private, loopback, or link-local address. Use a publicly reachable HTTPS URL. For local development, put a tunnel in front of your server and register the tunnel's public URL.

Work through these in order:

• Confirm the subscription is active.
• Check the events filter. If you subscribed to specific event types, only those are delivered; omit events to receive all of them.
• Make sure your endpoint answers with a 2xx quickly. Non-2xx responses are treated as failures and retried with backoff.
• Inspect the delivery history endpoint to see attempts, status codes, and retry state.

Compute the HMAC-SHA256 over the exact raw request body bytes, using your subscription's signing secret, and compare against the hex digest in X-TagLogger-Signature (formatted sha256=<hex>). The two most common mistakes are hashing a re-serialized JSON object (which changes the bytes) instead of the raw body, and comparing against the whole header value without stripping the sha256= prefix. Use a constant-time comparison. See Webhook Delivery.

Delivery is at-least-once, so retries can occasionally deliver a duplicate. Make your handler idempotent: dedupe on the event id and treat a repeat as a no-op.

You exceeded the per-key limit. Honor the Retry-After header and back off. If you hit it routinely, poll the fleet delta endpoint instead of looping per-tag, and widen your interval. The polling guide shows patterns that stay well under the limit.

Share links can carry an expiry. Once a link is past its expiration it no longer resolves. Create a fresh link with manage:share-links when you need continued access.