Troubleshooting

Check your API key

Ensure your SOCWARDEN_API_KEY starts with sk_live_. Test keys (sk_test_) are not accepted by the production ingestor.

Verify the endpoint

Default endpoint: https://ingest.socwarden.com. Ensure no trailing slash. Test with curl:

curl -X POST https://ingest.socwarden.com/v1/events \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event":"test.ping"}'

Expected: 202 Accepted

Check event type format

Event types must match: ^[a-z][a-z0-9]{0,29}(\\.[a-z][a-z0-9_]{0,29}){1,3}$

Valid: auth.login.success, custom.payment.completed

Invalid: AUTH.LOGIN, login (single segment), a.b.c.d.e (5 segments)

Check API key scoping

If your API key has event type scopes configured, only matching events will be accepted. A scoped key returns 403 EVENT_TYPE_NOT_ALLOWED for non-matching types. Check your key settings in Dashboard → API Keys.

Free plan limit reached

The Free plan drops events after 2,500/month. Check Dashboard → Usage to see your current count. Upgrade to Starter ($12/mo) for 25,000 events with overage billing instead of drops.

Understanding rate limits

Rate limits are per API key:

SDK auto-backoff

All SOCWarden SDKs handle 429 automatically with exponential backoff: 1-hour cooldown after first 429, 5-minute probe retries, auto-resume on success. Events during backoff are silently dropped — they are NOT queued.

Response headers

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1711234560

Check plan-gated detections

Some detections are only available on specific plans:

• Free: Brute force, request anomaly scanning only
• Starter+: Impossible travel, geo-anomaly, outside business hours, data exfiltration
• Pro+: Session anomaly, credential spray, kill chains, account takeover sequences, payment fraud

Alert cooldowns

SOCWarden uses progressive alert cooldowns to prevent alert fatigue: 1st alert delivers immediately, 2nd within 24h suppressed for 6 hours, 3rd for 12 hours, 4th+ for 24 hours. FLASH-tier alerts bypass all cooldowns.

Check notification channels

Alerts are generated but notifications depend on your configured channels (Dashboard → Notifications). Free plan: email only. Starter: email + Telegram. Pro: + Slack, Discord, Webhook.

GeoIP showing "Unknown"

Private/internal IPs (10.x, 172.16.x, 192.168.x, 127.0.0.1) cannot be geolocated. Ensure you're sending the client's public IP, not your server's internal IP. The SDK middleware auto-extracts the client IP from X-Forwarded-For.

OSINT enrichment empty

Layer 3 OSINT enrichment (AbuseIPDB, GreyNoise, Pulsedive) only runs on high/critical risk events (risk score ≥ 50). Low-risk events only get GeoIP + threat feed matching. This is by design to conserve API quotas.