Admaxxer Pixel API — Errors

Every API error response uses the same envelope. The HTTP status line indicates the class; the error.code string gives you a stable identifier you can branch on in client code.

Response Envelope

{
  "error": {
    "code": "insufficient_scope",
    "message": "This endpoint requires the 'pixel:write' scope",
    "details": { "required": "pixel:write", "available": ["pixel:read"] }
  },
  "meta": { "request_id": "req_abc123" }
}

Include the request_id in any support email — it lets us pull your exact request out of the server logs.

Error Codes

HTTP	Code	Meaning & Fix
401	`missing_authorization`	No `Authorization` header. Add `Authorization: Bearer YOUR_KEY`.
401	`invalid_authorization_format`	Header was present but not in `Bearer <key>` form.
401	`invalid_api_key`	Key does not match any stored hash. Check for trailing whitespace, env vars from the wrong environment, or a pasted hash vs raw key.
401	`api_key_revoked`	Key’s `revoked_at` is set. Create a new one.
401	`api_key_expired`	Key’s `expires_at` has passed. Create a new one.
403	`insufficient_scope`	Key exists but lacks the scope required for this route. `details.required` names the scope; add it and rotate.
400	`invalid_pipe`	The `pipe` path segment was not in the allowlist. See Endpoints.
400	`invalid_visitor`	The `/visitors/{id}` id was empty after trimming.
400	`invalid_body`	Zod validation failed on POST body. `details` contains field-level errors.
429	`rate_limit_exceeded`	Caller exceeded 60 req/minute. Respect the `Retry-After` header.
503	`ingest_unavailable`	Tinybird ingest env var is missing on this server. Contact support.
503	`identify_unavailable`	Identify ingest env var is missing. Contact support.
503	`tinybird_error`	Downstream Tinybird config error. Retry after a short backoff.
500	`internal_error`	Unhandled server error. The `request_id` is your best lead for support.

Retry Strategy

Never retry 4xx other than 429 — the request is wrong and a retry will not fix it.
Retry 429 after Retry-After seconds. Add jitter.
Retry 500 and 503 with exponential backoff: 1s, 2s, 4s, 8s, 16s. Give up after 5 attempts.
Make POSTs idempotent on your side (client-assigned IDs, dedup tables) so safe to retry.

Common Troubleshooting

“Works in dev, 401 in prod.” You deployed the dev key. Keys are environment-scoped because the hash table is different per database.
“403 on every request.” The key exists but has no scopes. Recreate it with explicit scopes from Settings › API Keys.
“JWT expired” from Tinybird. Minted JWTs live for 120 seconds. Re-mint on every request instead of caching.
“Empty data on a fresh website.” Not an error — the pipe returns an empty array until the first pageview. Fire a test event with POST /pixel/events.

Overview · Auth · Endpoints · Rate Limits

Admaxxer Pixel API — Errors

Response Envelope

Error Codes

Retry Strategy

Common Troubleshooting

Related