> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanova.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Verify & Debug Server Events

> Confirm your server-side conversion events are being received, attributed correctly, and appearing in reports.

## Step 1: Send a test event

Send a single test event with a known `event_id` so you can trace it:

```bash theme={null}
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 }
  }'
```

A successful response looks like:

```json theme={null}
{
  "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

Resend the same request with the same `event_id`:

```bash theme={null}
# 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"
  }'
```

The second request will return `200` but the event will be marked as a duplicate and excluded from conversion counts. Confirm the event count in reports did not increase.

***

## Common errors and fixes

### `401` — Missing API key

The `X-API-Key` header is absent from the request.

```bash theme={null}
# 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

Either the API key is invalid, revoked, or the `site_id` in the payload does not match the site the key belongs to. Verify:

* 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

The payload failed schema validation. The response body includes details:

```json theme={null}
{
  "detail": [
    {
      "loc": ["body", "scan_session_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

Common causes:

* 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

You are sending more than 1,000 events per minute per API key. Back off and retry:

* 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