Behandelt API-Fehler, Ratenbegrenzungen und Wiederholungsversuche der Klasse Notiondesk

Die Notiondesk-API beantwortet jeden Fehler mit demselben JSON-Envelope und einem maschinenlesbaren code-Header, beschränkt jeden Schlüssel auf 120 Lese- und 20 Schreibvorgänge pro Minute und ermöglicht es Ihnen, jede Änderung sicher mit einem Idempotency-Key-Header zu wiederholen. Dieser Artikel listet alle Fehlercodes der Notiondesk-API auf, erläutert die Ratenbegrenzungen und ihre Header und zeigt, wie Sie Wiederholungsversuche erstellen, die niemals zweimal Änderungen vornehmen.

Der API-Fehlerumschlag Notiondesk

Jeder Fehler hat die gleiche Form, und jedes Feld ist immer vorhanden:

{
  "object": "error",
  "code": "validation_error",
  "message": "The request parameters are invalid.",
  "request_id": "0f2c1e94-7a1b-4c2d-9e3f-5a6b7c8d9e0f",
  "errors": [
    {"field": "page_size", "message": "This value should be between 1 and 100."}
  ]
}

Wie field einen Wert benennt

• Ein Feld der obersten Ebene ist sein Name: page_size.

• Ein Feld innerhalb einer Liste benennt die Liste, den Eintrag in Klammern und dann das Feld: items[fr].page_title.

• Die Klammer enthält die Kennung des Eintrags, wie Sie sie übermittelt haben (z. B. locale in items, category_id in changelog_categories), sofern jeder Eintrag eine eindeutige Kennung besitzt. Andernfalls enthält sie die nullbasierte Position des Eintrags: items[0].locale.

• Ein Problem mit der Anfrage als Ganzes hat "field": null.

Notiondesk API-Fehlercodes

Eine Anfrage an ein Hilfecenter oder eine Ressource außerhalb Ihres Arbeitsbereichs wird mit dem Fehlercode 404 not_found beantwortet, sodass die API niemals offenlegt, ob diese existiert.

Notiondesk API-Ratenbegrenzungen

Jeder API-Schlüssel und jede OAuth-Berechtigung verfügt über zwei Anfragebudgets, die innerhalb eines gleitenden Ein-Minuten-Fensters gezählt werden:

Die Analyseberichte werden auch auf ein Budget von 30 Anfragen pro Minute pro Hilfezentrum angerechnet, das von allen Schlüsseln und OAuth-Apps des Arbeitsbereichs gemeinsam genutzt wird.

Die Antworten enthalten drei Überschriften:

Eine Anfrage über das Budget hinaus beantwortet 429 rate_limited. Warten Sie die in Retry-After angegebene Anzahl Sekunden, bevor Sie die nächste Anfrage senden.

Hinweis: Ratenbegrenzungen gelten pro Schlüssel bzw. pro OAuth-Grant, nicht pro Workspace. Zwei Integrationen mit separaten Schlüsseln verlangsamen sich nicht gegenseitig, außer beim gemeinsamen Analysebudget.

Sicherer Neustart mit Idempotency-Key

Bei einem Netzwerk-Timeout ist unklar, ob eine Änderung erfolgreich war. Der Header Idempotency-Key ermöglicht es Ihnen, dieselbe Anfrage erneut zu senden, ohne die Änderungen zweimal vornehmen zu müssen.

Jede Route, die eine Änderung vornimmt, akzeptiert diese: Änderungen an Seitenweiterleitungen, Aktualisierungen von Einstellungen und Branding, Änderungen an Integrationen und Synchronisierungsauslöser. Senden Sie beim ersten Versuch einen eindeutigen Wert von 1 bis 255 Zeichen, z. B. eine UUID, und denselben Wert bei jedem weiteren Versuch.

Was passiert bei einem Wiederholungsversuch?

curl -X POST "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/page-redirects" \
  -H "Authorization: Bearer $NOTIONDESK_API_KEY" \
  -H "nd-version: 2026-10-16" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f0d6b1e-create-getting-started" \
  -d '{"type": "article", "source_path": "/legacy/getting-started", "target_id": "1761580412", "locale": "en"}'

Eine erfolgreiche Antwort enthält beim ersten Mal X-Idempotent-Replay: false und bei einer Wiederholung true. Notiondesk speichert einen Schlüssel mindestens 24 Stunden lang. Ein Schlüssel gehört zum API-Schlüssel oder OAuth-Grant, der ihn gesendet hat, und ein OAuth-Grant behält seine Schlüssel auch nach Token-Aktualisierungen bei.

Ohne den Header wird eine Anfrage einmal ausgeführt, und ein Wiederholungsversuch wird erneut ausgeführt.

Eine Wiederholungsstrategie, die funktioniert

1. Erzeuge pro logischer Änderung ein Idempotency-Key und verwende es bei jedem Wiederholungsversuch dieser Änderung wieder.

2. Bei 429 rate_limited warte Retry-After Sekunden und versuche es dann erneut.

3. Warten Sie bei 409 request_in_progress einige Sekunden und versuchen Sie es dann mit demselben Schlüssel erneut. Bei 409 conflict_error läuft bereits eine Synchronisierung des Hilfecenters: Warten Sie einige Minuten, bevor Sie den Vorgang erneut auslösen, oder überspringen Sie diesen Lauf.

4. Bei 500 und höher oder einem Netzwerkfehler wird ein erneuter Versuch mit exponentiellem Backoff unternommen, beispielsweise nach 1, 2, 4 und 8 Sekunden.

5. Versuchen Sie niemals, 400, 401, 403, 404 oder 422 unverändert erneut anzufordern. Korrigieren Sie zuerst die Anfrage.

In JavaScript stoppt die Ausführung bei jeder Route, die etwas ändert, bei conflict_error und überlässt die Entscheidung Ihrem Code.

Häufig gestellte Fragen

import { randomUUID } from "node:crypto";

const sleep = (seconds) => new Promise((resolve) => setTimeout(resolve, seconds * 1000));

async function notiondeskRequest(method, path, body, attempts = 5) {
  const idempotencyKey = randomUUID();

  for (let attempt = 0; attempt < attempts; attempt++) {
    let response;
    try {
      response = await fetch(`https://api.notiondesk.so${path}`, {
        method,
        headers: {
          Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
          "nd-version": "2026-10-16",
          "Content-Type": "application/json",
          "Idempotency-Key": idempotencyKey,
        },
        body: body ? JSON.stringify(body) : undefined,
      });
    } catch {
      await sleep(2 ** attempt);
      continue;
    }

    if (response.ok) {
      return response.status === 204 ? null : response.json();
    }

    const error = await response.json().catch(() => ({}));
    const retryable = response.status === 429 || response.status >= 500 || error.code === "request_in_progress";
    if (!retryable) {
      throw new Error(`${response.status} ${error.code}: ${error.message}`);
    }

    const retryAfter = Number(response.headers.get("Retry-After"));
    await sleep(retryAfter > 0 ? retryAfter : 2 ** attempt);
  }

  throw new Error(`Notiondesk request failed after ${attempts} attempts`);
}

Was kommt als Nächstes?

• Paginierung und Versions-API-Anfragen Notiondesk

• Authentifizieren Sie sich mit der Notiondesk API mithilfe der API-Schlüssel.

• Legen Sie los mit der Notiondesk REST-API.