3 Min. Lesedauer

Request-ID-Header

Jede Antwort von api.zenovay.com enthält einen x-request-id-Header. Es ist die einzige Information, mit der der Zenovay-Support einen bestimmten API-Aufruf von Ihrem Client durch die internen Logs der Plattform nachverfolgen kann.

Wie sie aussieht

x-request-id: 01HVNXT7K8M3F2Y9R6P4ZQAB1C

Jede Anfrage erhält eine eindeutige 26-stellige ULID, die am Edge generiert wird. Die ID wird außerdem an jeden Fehlerbericht angehängt, den Zenovays Monitoring erfasst, sodass eine einzige Zeichenfolge zusammenführt, was Ihr Client gesehen hat und was die Logs der Plattform aufgezeichnet haben.

Wann sie erscheint

Bei jeder erfolgreichen Antwort (2xx) — nützlich für nachträgliches Debugging, falls im Nachhinein etwas seltsam aussah
Bei jeder Fehlerantwort (4xx, 5xx) — der nützlichste Fall; fügen Sie sie Ihrem Support-Ticket bei
Tracker-Ingestion — Pageview-, Event- und Revenue-Aufrufe tragen sie alle
REST API- und CLI-Endpunkte — /api/external/v1/*, /v1/cli/*, MCP usw.
Authentifizierungs-Endpunkte — Aufrufe an auth.zenovay.com enthalten sie ebenfalls

Wie Sie sie aus Ihrem Code auslesen

Aus `fetch`-Antworten

const response = await fetch('https://api.zenovay.com/api/external/v1/...', {
  headers: { Authorization: `Bearer ${apiKey}` },
});

const requestId = response.headers.get('x-request-id');

if (!response.ok) {
  console.error(`Zenovay API error (request ${requestId}):`, response.status);
}

Aus `axios`

try {
  const result = await axios.get('https://api.zenovay.com/api/external/v1/...', {
    headers: { Authorization: `Bearer ${apiKey}` },
  });
  console.log('request id:', result.headers['x-request-id']);
} catch (err) {
  console.error('failed; request id:', err.response?.headers?.['x-request-id']);
}

Aus `curl`

Fügen Sie -i hinzu, um die Antwort-Header auszugeben:

curl -i https://api.zenovay.com/api/external/v1/analytics/<websiteId>/visitors \
  -H "Authorization: Bearer YOUR_KEY"

Wie Sie sie mit dem Support nutzen

Wenn etwas schiefgeht:

Erfassen Sie die x-request-id aus der fehlgeschlagenen Antwort.
Geben Sie sie in Ihrem Support-Ticket oder Community-Beitrag an — wortgetreu, in einem Code-Block.
Notieren Sie den ungefähren UTC-Zeitstempel des Aufrufs (auf die Minute genau reicht meist).
Wenn möglich, geben Sie auch die Anfrage-URL und den Response-Statuscode an.

Mit diesen vier Informationen kann der Zenovay-Support den genauen Aufruf in der Regel innerhalb von Sekunden finden und Ihnen sagen, warum er fehlgeschlagen ist.

Logging-Tipps

Erfassen Sie für Produktionscode, der die Zenovay API aufruft, x-request-id auf jedem Fehlerpfad:

function logZenovayError(label, response) {
  const requestId = response.headers.get('x-request-id') ?? 'unknown';
  console.error(`[zenovay:${label}] status=${response.status} req=${requestId}`);
}

Wenn Sie einen strukturierten Logger verwenden (pino, winston, datadog, sentry usw.), legen Sie die Request-id als strukturiertes Feld ab, anstatt sie in die Nachricht einzubetten — so können Sie danach suchen und gruppieren.

CORS

x-request-id wird über den Response-Header Access-Control-Expose-Headers an jedem CORS-fähigen Endpunkt freigegeben, sodass Browser sie ohne zusätzliche Konfiguration auf Ihrer Seite aus JavaScript auslesen können.

Was Sie mit der Request-id nicht tun sollten

Versuchen Sie nicht, Informationen aus ihr zu reverse-engineeren. Es ist eine ULID, kein codierter Payload.
Verwenden Sie sie nicht als Deduplizierungsschlüssel — Zenovay handhabt Idempotenz separat, auf den Ressourcen, die sie benötigen.
Stellen Sie sie nicht auf einer öffentlich zugänglichen Oberfläche zur Schau (eine generische „Etwas ist schiefgelaufen"-Seite ist in Ordnung; eine „Anfrage 01HVNX... fehlgeschlagen"-Seite auf einer öffentlichen Marketing-Seite ist mehr Information, als Ihre Besucher benötigen).