Ingest API (DSN)
Die Ingest API ist der öffentliche Endpoint, der Error-Events, Transaktionen, Logs und Session Replays von deinen SDKs empfängt.
Endpoint
POST https://app.unseenr.io/api/{projectId}/envelope
Wobei {projectId} die numerische ID oder CUID deines Projekts ist.
Authentifizierung
Die Authentifizierung erfolgt über den Public Key aus deiner DSN. Der Key kann auf drei Arten bereitgestellt werden:
- Query-Parameter:
?sentry_key=<PUBLIC_KEY> - x-unseenr-auth Header:
x-unseenr-auth: sentry_key=<PUBLIC_KEY> - x-sentry-auth Header:
x-sentry-auth: sentry_key=<PUBLIC_KEY>(Sentry SDK kompatibel)
Request-Format
Der Body nutzt Sentrys Envelope-Format: eine durch Zeilenumbrüche getrennte Sequenz aus JSON-Headern und Payloads.
{"event_id":"...","dsn":"..."}
{"type":"event","length":...}
{"exception":{"values":[...]},"event_id":"...","timestamp":...}
Unterstützte Envelope-Typen
| Typ | Beschreibung |
|---|---|
event |
Error-Events (Exceptions, Nachrichten) |
transaction |
Performance-Transaktionen mit Spans |
log |
Strukturierte Log-Einträge |
replay_event |
Session-Replay-Metadaten |
replay_recording |
Session-Replay-Aufzeichnungsdaten (gzip) |
Antwort
Erfolg (200)
{
"id": "32-zeichen-event-id"
}
Antwort-Header
| Header | Beschreibung |
|---|---|
X-Unseenr-Usage |
{aktuell}/{kontingent} z.B. 4821/5000 |
X-Unseenr-Usage-Percent |
Verbrauch in Prozent als Integer |
X-Unseenr-Quota-Warning |
true wenn Verbrauch über 75% |
X-RateLimit-Remaining |
Verbleibende Anfragen im aktuellen Fenster |
X-RateLimit-Reset |
Zeitstempel wann Rate Limit zurücksetzt |
Fehlerantworten
| Status | Body | Ursache |
|---|---|---|
| 401 | {"error":"Missing authentication"} |
Kein Public Key angegeben |
| 401 | {"error":"Invalid project or key"} |
Falsche Projekt-ID oder Public Key |
| 413 | {"error":"Payload too large"} |
Body überschreitet 5 MB |
| 429 | {"error":"Rate limit exceeded"} |
Pro-Minute Rate Limit erreicht |
| 429 | {"error":"quota_exceeded"} |
Monatskontingent überschritten und Overage deaktiviert |
| 400 | {"error":"Invalid envelope format"} |
Nicht parsbares Envelope |
| 500 | {"error":"Internal server error","errorId":"..."} |
Server-Fehler (errorId für Support) |
CORS
Der Ingest-Endpoint hat permissive CORS-Header für Browser-SDKs. Null-Origin ist für serverseitige SDKs erlaubt.
Request-Größenlimit
Die maximale Request-Body-Größe ist 5 MB. Größere Payloads werden mit HTTP 413 abgelehnt.
Verarbeitungspipeline
- Authentifizierung: Public Key gegen Projekt validieren
- Rate Limiting: Pro-Minute-Rate-Limit prüfen (vor Kontingent)
- Eingangsfilter: Browser-Extension-, Localhost-, Crawler- und Origin-Filter anwenden (vor Kontingent)
- Kontingent-Check: Atomarer Redis-Increment mit TTL
- Queue: In BullMQ für asynchrone Verarbeitung durch den Worker einstellen
- Antwort: Event-ID sofort zurückgeben
Events werden zum Zeitpunkt der HTTP-Annahme (Schritt 4) abgerechnet, nicht nach asynchroner Verarbeitung. Dies ist der Industriestandard (identisch mit Sentry, Datadog, PostHog).