Troubleshooting – common issues

Events not appearing in Event stream

• Check ingest URL and credentials
  Use the exact ingest URL, App UUID, and API secret from your app settings.
  Requests must include:

  • x-app-uuid
  • x-signature (HMAC-SHA256 over the raw body)

  Wrong URL, unknown app UUID, or invalid signature will result in 401 or 404.

• Signature mismatch (very common)
  The x-signature must be computed over the exact raw request body bytes.
  If your JSON formatting changes (extra spaces, different key order), the signature will not match.
  Ensure you:

  • Build the body once
  • Compute HMAC over that exact string
  • Send that exact string as the request body

• Check response status

  • 401 → Invalid signature
  • 404 → Unknown or inactive app UUID
  • 400 → Schema validation error

  Inspect the response body for details.

• Environment filter
  If you send environment, ensure the Event stream filter in the UI matches (e.g. production vs staging).

• Timing
  Events typically appear within seconds. If not, check client logs, server logs, and network errors.

Events appear but organization missing

• Ensure you send a valid customer_org_id.
• Organization lists are generated from event data; if you send events without customer_org_id, they will not appear in Analytics → Organizations.
• customer_org_id is case-sensitive.

403 on app or feature

• Org health model
  Configuring the org health model requires the health_model_config feature (Growth plan and above).
  If you see 403 or an “Upgrade required” message, your plan does not include this feature.

• Applications limit reached
  You may have reached the apps_max limit for your plan.
  Check Billing / Plan and remove an app or upgrade.

Cannot add another application

Your plan has an apps_max limit.
The “Add application” button is disabled when the limit is reached.

Exact limits are visible on the Billing / Plan page.

Overage banner

You have exceeded a soft plan limit (e.g. events this month).

• Ingest is not blocked.
• Events continue to be stored.
• The UI shows an overage banner and may suggest a higher plan.

Go to Billing / Plan to review usage or request an upgrade.

Data or retention questions

• Retention
  Raw data retention depends on your plan and subscription overrides.
  See Privacy and retention and the Billing / Plan page.

• Missing historical data
  If older data is missing:

  • Check retention limits.
  • Verify that the app and environment existed at that time.
  • Confirm events were sent with the correct x-app-uuid.

AI cost shows as unknown or zero incorrectly

• unknown_model — provider + model did not match the global catalog or an alias. Use API model ids (e.g. gpt-5.4-mini) or ask your SaaS Tracker operator to add an alias (Admin portal → Unmapped AI models).
• missing_price — Model is known but has no applicable unit price (common for local:* models until customer pricing is configured).
• missing_tokens — Catalog pricing needs input_tokens and output_tokens on ai_call_completed (failed calls without tokens are intentionally not costed).
• Explicit zero — Send estimated_cost_eur: 0 (or cost_amount + cost_currency) when cost is truly zero; omit the field when unknown.
• ClickHouse — Cost resolution fields require migration 003_ai_usage_cost_resolution.sql on the analytics database.

See Tracking AI usage.

Next: 10-minute guide or Ingest API overview.