Scopes und Fehler

Jede Operation der öffentlichen API erfordert einen expliziten Scope. Ein gültiger Zugangsschlüssel ohne diesen Scope erhält 403 insufficient_scope; er wird nie stillschweigend auf einen umfassenderen Zugriff erweitert.

Scope-Referenz#

Verwenden Sie für Reporting-Jobs Lese-Scopes. Fügen Sie einen Schreib-Scope nur hinzu, wenn die Integration diese Änderung tatsächlich durchführt. Ein Lead-Export benötigt beispielsweise normalerweise sites:read und leads:read, nicht jedoch sites:write oder agents:write.

Scope-Fehler#

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key does not grant the required scope.",
    "details": { "required": ["sites:write"] },
    "request_id": "6c0b2f2e-..."
  }
}

Fügen Sie den fehlenden Scope dem Schlüssel unter Einstellungen → Entwickler → Bearbeiten hinzu, oder erstellen Sie einen Ersatzschlüssel und aktualisieren Sie das Server-Secret. Beim Bearbeiten werden Name und Scopes des Schlüssels direkt geändert; Ablaufdatum und Token bleiben gleich. Über OAuth ausgestellte Schlüssel können nicht bearbeitet werden; verbinden Sie die Anwendung erneut, um die erteilten Berechtigungen zu ändern.

Fehlerstruktur#

Alle API-Fehler verwenden dieselbe Struktur auf oberster Ebene:

type ApiError = {
  error: {
    code: string;
    message: string;
    details?: unknown;
    request_id: string;
  };
};

Verzweigen Sie anhand von error.code, nicht anhand der englischen message. Meldungen können ohne Versionswechsel verbessert werden. Protokollieren Sie error.request_id und den Response-Header x-request-id zusammen mit Operationsname, Status und Wiederholungsversuch – protokollieren Sie jedoch niemals den Authorization-Header oder geheime Anfragedaten.

Referenz zu Status und Codes#

Ressourcen außerhalb des Kontos des Zugangsschlüssel-Owners können 404 zurückgeben, damit nicht offengelegt wird, ob die ID eines anderen Mandanten existiert.

Validierungsdetails#

Die Feldvalidierung gibt Pfade zurück, die Sie neben Ihren eigenen Formularfeldern anzeigen können:

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      { "path": "content.headline", "message": "String must contain at least 1 character(s)" }
    ],
    "request_id": "6c0b2f2e-..."
  }
}

Bodys von Mutationen müssen JSON-Objekte sein. Arrays, leere Bodys, Formulardaten und JSON, das mit einem Text-Content-Type gesendet wird, werden abgelehnt.

Entscheidungen zu Wiederholungen#

• Wiederholen Sie 429 nach der in Retry-After angegebenen Anzahl von Sekunden.
• Wiederholen Sie 500 nur bei sicheren Lesevorgängen oder bei Schreibvorgängen, die mit demselben Idempotency-Key geschützt sind.
• Wiederholen Sie das 409 der laufenden Idempotenzprüfung nach dem Header Retry-After: 2.
• Wiederholen Sie 503 outcome_unknown niemals blind. Prüfen Sie zuerst die Ressource; verwenden Sie einen neuen Idempotency-Key erst, nachdem Sie bestätigt haben, dass die Änderung nicht erfolgt ist.
• Wiederholen Sie 400, 401, 403, 404, 413 oder einen Zustandskonflikt nicht, bevor sich die Ursache geändert hat.

Informationen zum Backoff-Verhalten finden Sie unter Rate limits, den erforderlichen Scope für jede Operation unter API reference.