Troubleshooting
Events not showing up
Check that your project key starts with pk_ followed by 22 base64url characters. Secret key must be exactly 43 characters. Copy from project settings directly, as extra spaces or newlines will break validation.
If you set a custom endpoint, make sure it’s reachable. Default is https://kohicorp.com/api/ingest.
Guard error responses
These are HTTP errors returned by the ingest endpoint. If your SDK logs show any of these, here’s what they mean:
| Status | Message | Cause |
|---|---|---|
| 400 | invalid project key | Project key doesn’t match pk_ + 22 chars format |
| 400 | invalid signature | Missing or malformed X-Signature header (must be 64 hex characters) |
| 400 | content-encoding must be gzip | Payload wasn’t gzip-compressed |
| 400 | invalid gzip / invalid gzip payload | Corrupted gzip data |
| 400 | decompressed payload too large | Payload exceeds 10MB after decompression |
| 400 | batch too large: N events (max 500) | Too many events in one batch |
| 401 | unauthorized | Project key not found in database |
| 401 | signature mismatch | Secret key doesn’t match; re-copy from project settings |
| 403 | project disabled | Project has been disabled |
| 413 | payload too large | Compressed body exceeds 2MB |
| 429 | rate limit exceeded | Per-tenant rate limit hit (requests per minute/hour/day) |
| 429 | monthly quota exceeded | Plan quota used up |
Wrong client IPs
The SDK reads proxy headers in this order: CF-Connecting-IP, X-Vercel-Forwarded-For, X-Forwarded-For, X-Real-IP, X-Cluster-Client-IP, Fastly-Client-IP, Forwarded (RFC 7239). Make sure your proxy forwards at least one.
Next.js: nothing captured
Only /api/* routes are recorded. Static pages and _next/* are skipped.
instrumentation.ts must be in your project root (not app/ or src/). Must export async function register() with NEXT_RUNTIME === "nodejs" guard and dynamic import(). Requires Next.js 14+.
High memory usage (Go)
Call monitor.Close() on shutdown (use defer). This flushes the buffer and stops background goroutines.
Rate limiting
The SDK automatically retries 429 responses with exponential backoff (250ms base, 2s max, 3 attempts). Rate limits are per-tenant, shared across all projects in your account. Check your limits in Settings > Plan.
If you’re still stuck, check the configuration reference to make sure your SDK options are set correctly.