Verify & Debug Server Events

​

Step 1: Send a test event

curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002",
    "properties": { "test": true }
  }'

{
  "event_id": "00000000-0000-0000-0000-000000000001",
  "status": "accepted"
}

​

Step 2: Confirm it appears in the dashboard

1. Open the Scanova dashboard
2. Go to Integrations → Conversion Tracking
3. Open the tracking site
4. Your test_event should appear within 30–60 seconds

​

Step 3: Test deduplication

# Same request again
curl -X POST "https://track.scanova.io/server-events" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "site_id": "YOUR_SITE_ID",
    "event_name": "test_event",
    "event_id": "00000000-0000-0000-0000-000000000001",
    "scan_session_id": "00000000-0000-0000-0000-000000000002"
  }'

​

Common errors and fixes

​

401 — Missing API key

# Wrong — missing header
curl -X POST "https://track.scanova.io/server-events" -d '{...}'

# Correct
curl -X POST "https://track.scanova.io/server-events" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{...}'

​

403 — Invalid key or unauthorized site

• The key was copied correctly (no trailing spaces or newline characters)
• The site_id in the request body matches exactly the site that generated the key
• The key has not been revoked in the dashboard

​

422 — Validation error

{
  "detail": [
    {
      "loc": ["body", "scan_session_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

• Missing required field (site_id, event_name, or scan_session_id)
• scan_session_id is not a valid UUID format
• conversion_value.currency is not a 3-letter ISO code
• properties object exceeds 10 KB
• Raw email address in properties (use user_identifiers.email_hash instead)

​

429 — Rate limit exceeded

• Check the Retry-After header in the response
• Use the batch endpoint (POST /server-events/batch) to consolidate multiple events into fewer requests

​

Event delivered but not appearing in reports

• Wait 60 seconds — there is a short processing delay
• Verify the site_id in your payload matches the tracking site you are viewing in the dashboard
• Check that the scan_session_id is a valid UUID — invalid format is rejected with 422
• Confirm the scan_session_id you sent is a real scan session from a QR Code scan, not a test UUID — events with unresolvable sessions are not attributed and may not appear in reports