API-Fehler — Was die einzelnen Codes bedeuten und wie Sie sie beheben

FastOG gibt maschinenlesbare Fehlercodes zurück, wenn eine Anfrage fehlschlägt — beim Rendern eines signierten OG-Bilds oder bei einem Aufruf einer der produktinternen Admin-Oberflächen. Jede Fehlerantwort enthält:

• error — das alte kurze Token. Es ist bei jedem Fehler weiterhin vorhanden, damit ein älterer Client weiter funktioniert.
• code — denselben stabilen, dokumentierten Fehlercode (Tabelle unten), unter dem Namen, den die öffentliche API verwendet.
• message — eine einzeilige Beschreibung dessen, was schiefgelaufen ist.
• hint — eine kurze, in einfacher Sprache gehaltene Beschreibung dessen, was schiefgelaufen ist und wie Sie es beheben.
• docs_url — einen Link auf diese Seite, verankert beim Abschnitt für diesen Code.
• request_id — ordnet diesen HTTP-Fehler einer Zeile in der Tabelle Render Logs im Dashboard zu (wird auch im Antwort-Header X-Request-ID zurückgegeben). Eine Oberfläche ohne Zuordnungsmöglichkeit antwortet mit null, aber der Schlüssel ist immer vorhanden.

Die produktinternen Oberflächen — das Shopify-Admin, das WooCommerce Studio, die Wix-Bridge und die Demo — antworten für die unten aufgeführten Codes mit demselben Envelope, sodass ein Fehler überall dasselbe bedeutet, wo Sie ihm begegnen. Eine Modul-Oberfläche kann den HTTP-Status beibehalten, den sie für einen Code schon immer zurückgegeben hat (zum Beispiel antwortet render_failed beim Cover-Export mit 503 und bei der öffentlichen API mit 502); Code, Meldung, Hinweis und Docs-Link ändern sich nicht.

Eine Fehlerantwort lesen

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

Wenn Sie eine Antwort erhalten, die Sie nicht verstehen, ist der schnellste Weg:

1. Notieren Sie den code.
2. Prüfen Sie Ihren URL-Builder — die meisten Fehler sind Signing-Bugs, keine Konto-Probleme.
3. Ordnen Sie den Code unten der genauen Ursache und Lösung zu.
4. Öffnen Sie im Dashboard Render Logs und filtern Sie nach demselben error_code — jede Zeile zeigt die angeforderten Parameter, sodass Sie den Fehler reproduzieren (und bestätigen können, dass request_id übereinstimmt).

Signieren & Authentifizierung

missing_signature

In Ihrer Anfrage fehlen die Query-Parameter key und/oder s (Signatur).

Behebung: Stellen Sie sicher, dass Ihre URL sowohl key=<api-key> als auch s=<hmac-signature> enthält. Verwenden Sie das SDK oder die /docs/hmac-signature-guide-Anleitung, um sie zu erstellen.

invalid_signature

Der Wert von s stimmte nicht mit dem überein, was Ihr HMAC-Secret für diese URL erzeugt.

Behebung: Die Signatur umfasst jeden Query-Parameter außer s, mit sortierten Schlüsseln. Jede Änderung an einem Parameter – einschließlich Umordnen, Unterschiede bei der URL-Kodierung oder hinzugefügter Leerzeichen – macht die Signatur ungültig. Signieren Sie nach jeder Änderung erneut. Vergewissern Sie sich, dass Ihr Secret dasselbe ist, das bei der Erstellung des API-Schlüssels angezeigt wurde.

invalid_signature_format

Der Wert von s ist keine 64-stellige Hex-Zeichenkette.

Behebung: Die Signatur muss rohes SHA-256-Hex sein (Kleinbuchstaben a-f0-9). Wenn Sie die Ausgabe base64-kodieren oder kürzen, verwenden Sie stattdessen reines Hex.

expired_timestamp

Der von Ihnen übergebene t-Zeitstempel ist älter als 5 Minuten.

Behebung: Erzeugen Sie den Zeitstempel jedes Mal neu, wenn Sie eine URL erstellen. Dieser Code gilt für den veralteten Signed-URL-Ablauf; der aktuelle HMAC-v2-Ablauf hat keinen Zeitstempel.

invalid_api_key

Der von Ihnen übergebene key existiert nicht.

Behebung: Kopieren Sie den vollständigen API-Schlüssel aus dem Dashboard – er ist die öffentliche Kennung, die mit sk_ beginnt. Er ist öffentlich und in URLs unbedenklich; das Secret (niemals in URLs) ist das, was den Besitz nachweist.

missing_hmac_secret

Für den API-Schlüssel ist kein HMAC-Secret konfiguriert.

Behebung: Erstellen Sie im Dashboard einen neuen API-Schlüssel – das HMAC-Secret wird bei der Erstellung generiert und einmalig angezeigt.

Parameter / Eingabe

invalid_image_url

Eine Prop mit URL (image, brand_logo, logo, avatar, background_image, ...) ist keine öffentliche http(s)-URL.

Behebung: Übergeben Sie eine öffentlich abrufbare https://...-URL. Localhost, private IPs und reine Pfade werden abgelehnt, um Server-Side Request Forgery zu verhindern.

Abonnement

subscription_required (402)

Die Anfrage hat die Dynamic API erreicht, aber Ihr Konto hat keinen aktiven Tarif. Der API-Zugriff ist nur mit Abonnement möglich: Der Tarif ist die Voraussetzung, und er umfasst dieselbe Abdeckungs- und Funktionsstufen wie die FastOG-Apps. Die Renders selbst werden nicht abgerechnet — es gibt kein monatliches Render-Kontingent und keine Abrechnung für Überschreitungen.

Lösung: Wählen Sie im Dashboard einen Dynamic-API-Tarif und erstellen Sie einen API-Schlüssel. Die Antwort enthält einen top_up_url, der auf die Tarifseite verweist.

Render-Dienst

store_blocked (403)

Das Rendering für den Store hinter diesem Schlüssel wurde von FastOG pausiert (zum Beispiel wegen Missbrauchs oder unkontrollierter Nutzung). Bereits am Edge zwischengespeicherte Cover können weiter ausgeliefert werden, bis sie ablaufen. Wenden Sie sich an den Support, um das Problem zu lösen; nichts, was Sie in der Anfrage ändern können, behebt dies.

render_unreachable

Der Render-Dienst war nicht erreichbar (kurzes Neustartfenster).

Behebung: Versuchen Sie es in einigen Sekunden erneut. Der Render wurde für diesen Versuch nicht gezählt.

render_failed

Der Render-Dienst hat für Ihre Anfrage einen Fehler zurückgegeben.

Behebung: Überprüfen Sie Ihre Template-Props — zu lange oder fehlerhafte Werte, nicht unterstützte Felder oder ein nicht erreichbares vorgelagertes Bild. Die Antwort enthält den zugrunde liegenden status. Der Render wurde nicht gezählt.

Store-Admin-Oberflächen

Diese Codes antworten aus dem Shopify-Admin und dem WooCommerce Studio — den eingebetteten Editoren, in denen ein Händler arbeitet, statt aus der signierten API. Mehrere werden mit der öffentlichen API geteilt (invalid_image_url, render_failed, invalid_signature); für diese bleibt der oben dokumentierte Eintrag bestehen.

Wix-Bridge

Die Wix-Bridge wird von der Wix-App signiert, nicht von einer Händlersitzung, daher richten sich ihre Fehler an den App-Entwickler. Jede Antwort enthält weiterhin code und request_id; die Bridge-Request-ID ist die aus dem signierten Envelope.

Demo-Oberfläche

Die Demo ist die nur für Eigentümer zugängliche Vertriebskonsole, kein Händler-Endpunkt.

Codes für den Editor für bereichsbezogene Regeln

Die Editoren für bereichsbezogene Regeln (Shopify-Admin und WooCommerce Studio) übersetzen diese Tokens selbst in die Sprache des Händlers, sodass ihre Antworten error und code enthalten, aber kein hint — eine zweite englische Beschreibung würde nur von der lokalisierten abweichen, die der Händler tatsächlich sieht:

scope_already_defined, scoped_rule_limit_reached, scoped_rules_not_on_plan, scope_value_required, scope_value_too_long, unknown_scope_type, base_rule_required, scoped_rules_product_only, cannot_delete_base_rule.

Kommen Sie nicht weiter?

• Öffnen Sie im Dashboard die Seite Render Logs — jedes Ergebnis (Erfolg + Ablehnung) ist dort mit seinem error_code, dem HTTP-Status und den angeforderten Parametern aufgeführt.
• Führen Sie php artisan og:diagnose auf einer signierten URL aus, um die gesamte Pipeline zu durchlaufen und zu sehen, welche Stufe fehlschlägt.
• Prüfen Sie in der Seitenleiste die Dokumentation für das von Ihnen verwendete Framework (Next.js, Express, SvelteKit, ...).