forbidden

HTTP 403 · code: "forbidden" · type: https://docs.formfeed.dev/errors/forbidden

Der Schlüssel ist gültig, aber diese Anfrage ist für ihn nicht erlaubt. Es gibt drei Arten der Ablehnung, und das Problem unterscheidet sie:

• Ein fehlender Scope. detail nennt ihn: This API key lacks the "template:write" scope.
• Eine Grenze des Plans. Das Problem trägt feature (was dem Plan fehlt), plan (den Plan der Organisation) und, wo der Plan eine Anzahl erlaubt, limit.
• Ein Aufrufer, der das nicht darf: ein Aufruf aus dem Browser, ein verbundener KI-Agent oder ein Mitglied ohne die nötige Rolle. detail sagt, welcher Fall.

Beispiel

Ein fehlender Scope:

{
  "type": "https://docs.formfeed.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "This API key lacks the \"template:write\" scope",
  "code": "forbidden",
  "request_id": "req_4b7c1e9a2f3d4c5b8a6e7f9012"
}

Eine Grenze des Plans:

{
  "type": "https://docs.formfeed.dev/errors/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "PDF post-processing (merge, password, watermark) is not part of the free plan; it starts with Starter",
  "code": "forbidden",
  "feature": "post_processing",
  "plan": "free",
  "request_id": "req_4b7c1e9a2f3d4c5b8a6e7f9012"
}

Häufige Ursachen

Fehlende Scopes:

• Vorlagen werden mit einem Schlüssel gepusht oder veröffentlicht, der nur die Standard-Scopes hat (nötig ist template:write).
• Webhooks werden ohne webhook:manage verwaltet, zum Beispiel wenn Zapier oder n8n einen Trigger registriert.
• Die Nutzung wird ohne account:read abgefragt, Ausgaben werden ohne file:delete gelöscht, die gespeicherte Anfrage eines Renderings wird ohne render:input gelesen, oder ein Workspace wird ohne workspace:delete gelöscht.

Grenzen des Plans (feature):

feature	Abgelehnt	Ab Plan
post_processing	/pdf/merge, /pdf/protect, /pdf/watermark oder ein post-Block mit merge_after, watermark oder password. /pdf/info funktioniert in jedem Plan.	Starter
office	/pdf/convert und Live-Renderings von Word- und PowerPoint-Vorlagen. Im Free-Plan erzeugen Test-Renderings dieser Vorlagen das markierte PDF.	Starter
channels	Rendern oder Setzen eines benannten Release Channels im Free-Plan; in Starter und Pro ein neuer Channel über die Anzahl pro Vorlage hinaus (mit limit: 2 in Starter, 10 in Pro und Business).	Starter
canary	Ein Channel mit Canary.	Pro
byo_storage	Das Verbinden eines Buckets für eigenen Speicher.	Pro
templates	Eine neue, kopierte oder wiederhergestellte Vorlage, wenn die Organisation schon die Anzahl des Plans hat (limit: 5 im Free-Plan). Archivierte Vorlagen zählen nicht.	Starter
webhooks	Ein neuer Webhook-Endpunkt, wenn die Organisation schon die Anzahl des Plans hat (limit: 1 im Free-Plan, 5 im Starter-Plan), deaktivierte eingeschlossen. Sitzungen von formfeed listen zählen nicht.	Pro
einvoice	Eine E-Rechnung aus einem Live-Rendering im Free-Plan; oder aus einem Test-Rendering, sobald die Test-E-Rechnungen des Tages aufgebraucht sind (Free 20, Starter 100, Pro 500, Business 2.000). Die zweite Antwort trägt limit, used und resets_at, den Beginn des nächsten UTC-Tages.	Starter (live)

Aufrufer, die das nicht dürfen:

• Eine Anfrage aus einer Webseite (detail: This API key may not be used from a browser origin): Ein API-Schlüssel funktioniert nur serverseitig; siehe Aus dem Browser. Die Portale von Power Automate, Power Apps und Copilot Studio sind nicht betroffen; ihre Connector-Aufrufe laufen über Microsofts Server.
• Ein verbundener KI-Agent (ein MCP-Client mit OAuth-Anmeldung) tut etwas, das nur eine Person darf (detail: A connected agent may not do this; sign in to Formfeed and do it there), oder ein Agent eines Kontos mit Zwei-Faktor-Authentifizierung, das ihn nie bestätigt hat.
• Die Routen unter /workspaces/{id}/storage und die Logos des Brand Kits: Diese verwalten nur Inhaber und Admins, die in der App angemeldet sind, nie ein API-Schlüssel.

So beheben Sie es

• Bei einem Scope: detail nennt ihn. Erstellen Sie einen Schlüssel, der ihn hat; einem bestehenden Schlüssel lassen sich keine Scopes hinzufügen. In der Scope-Tabelle steht, welcher Endpunkt welchen Scope braucht.
• Bei post_processing, office, channels, canary, byo_storage, templates oder webhooks: Wechseln Sie in einen höheren Plan. Mit Test-Schlüsseln in einem bezahlten Plan können Sie eine Funktion kostenlos ausprobieren. Bei channels können Sie auch weiter nur den Channel published rendern und verschieben, den jeder Plan hat; bei templates können Sie eine Vorlage archivieren, die Sie nicht mehr brauchen; bei webhooks einen Endpunkt löschen, den Sie nicht mehr brauchen (ein No-Code-Trigger entfernt seinen eigenen, wenn er ausgeschaltet wird).
• Bei einvoice: Rendern Sie zum Ausprobieren mit einem Test-Schlüssel, warten Sie bis resets_at, wenn der Tag aufgebraucht ist, oder rendern Sie live ab Starter, wo es keine Tageszahl gibt. Für ein gewöhnliches PDF aus einer Vorlage, die eine E-Rechnung festlegt, senden Sie "post": { "einvoice": false }.
• Bei einem Aufruf aus dem Browser: Rufen Sie die API aus Ihrem Backend auf und geben Sie dem Browser das Ergebnis, etwa die download_url des Renderings.
• Bei einem Agenten oder den Routen nur für die App: Erledigen Sie es in der App, angemeldet als Inhaber oder Admin.

Wiederholen?

Nein. Dieselbe Anfrage erhält dieselbe Antwort. Beheben Sie, was das Problem nennt, und senden Sie die Anfrage dann mit einem neuen Idempotency-Key oder ohne: Eine 4xx-Antwort wird 24 Stunden unter ihrem Schlüssel gespeichert, der alte Schlüssel liefert also wieder dieses Problem. Siehe Wiederholen.