Fehler

Jeder Fehlercode, den Ikiform zurückgibt, mit HTTP-Status, Ursache und Lösung.

Formular-Einsendungen und die REST-API teilen sich eine Fehlerhülle. JSON-Requests erhalten sie mit dem passenden HTTP-Status; Formular-Posts aus dem Browser erhalten eine gehostete Fehlerseite mit derselben Meldung und demselben Status.

Die Fehlerhülle

Fehler

{
  "ok": false,
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Please slow down."
  },
  "request_id": "req_01k7v2c9t3e8m5q4x6z0a1b2c3"
}

error.code ist stabil; verzweige danach. error.message ist einfaches Englisch für Menschen und kann sich ändern.
error.fields ist bei Validierungsfehlern vorhanden, nach Feld-ID geschlüsselt, jeweils mit einer Liste von Meldungen. Fehler, die den ganzen Body betreffen, nutzen den Schlüssel _form.
error.challenge_url ist bei challenge_required vorhanden.
request_id entspricht dem Header X-Request-Id, den jede Antwort trägt.
Antworten mit Rate-Limit tragen Retry-After in Sekunden. Beide Header sind aus Browser-Code lesbar.

Codes

Status	Code	Wo
400	`invalid_body`	Absenden
400	`invalid_request`	API
401	`unauthorized`	API
402	`plan_required`	Absenden
402	`test_limit_reached`	Absenden
403	`forbidden`	Beide
403	`origin_not_allowed`	Absenden
403	`form_paused`	Absenden
403	`captcha_failed`	Absenden
403	`challenge_required`	Absenden
404	`not_found`	Beide
405	`method_not_allowed`	API
409	`idempotency_in_progress`	Absenden
413	`payload_too_large`	Absenden
415	`unsupported_media_type`	Absenden
415	`unsupported_charset`	Absenden
422	`validation_failed`	Absenden
422	`files_not_supported`	Absenden
422	`too_deep`	Absenden
422	`idempotency_mismatch`	Absenden
429	`rate_limited`	Beide
429	`quota_exceeded`	Absenden
500	`server_error`	Beide

400 invalid_body

Meldung	`The request body could not be read.`
Ursache	Fehlerhaftes JSON oder Multipart, ein JSON-Array oder -String statt eines Objekts, oder ein Idempotenzschlüssel mit mehr als 255 Zeichen.
Lösung	Sende ein einzelnes JSON-Objekt, oder lass den Browser oder `FormData` den Body bauen.

400 invalid_request

Meldung	`The request is invalid.`
Ursache	`limit`, `status`, `form_id` oder `cursor` ist ungültig. Die Meldung nennt den Parameter.
Lösung	Nutze `limit` 1 bis 100, `status` `received` oder `spam`, eine echte `frm_`-ID und Cursor genau so, wie sie zurückgegeben wurden.

401 unauthorized

Meldung	`A valid API key is required.`
Ursache	Kein Header `Authorization`, kein Bearer-Token, oder ein unbekannter, widerrufener oder abgelaufener Schlüssel.
Lösung	Sende `Authorization: Bearer ik_sk_...` mit einem gültigen Secret Key.

402 plan_required

Meldung	`This form isn't accepting submissions right now.`
Ursache	Der Workspace hat keinen aktiven Tarif. Posts von einer Live-Site werden gespeichert und 30 Tage lang zurückgehalten, bis zu 100 pro Monat, und die Meldung sagt dann, dass die Einsendung gespeichert wurde. Spam und Posts darüber hinaus werden nicht gespeichert.
Lösung	Wähle einen Tarif oder kauf ein Einsendungspaket unter Settings › Plan and usage. Zurückgehaltene Einsendungen kommen an, sobald eines davon startet. Siehe Testen ohne Tarif.

402 test_limit_reached

Meldung	`This workspace used its test submissions for this month. Pick a plan to keep sending.`
Ursache	Der Workspace hat keinen Tarif und diesen Monat schon 50 Test-Einsendungen von `localhost` erhalten.
Lösung	Wähle einen Tarif oder warte auf den nächsten Monat. „Test senden“ im Dashboard funktioniert weiterhin.

403 forbidden

Meldung	`You do not have access to this resource.`
Ursache	Der API-Schlüssel ist fehlerhaft, gehört zu einem anderen Workspace, ist bei der REST-API ein Publishable Key oder hat nicht den nötigen Scope.
Lösung	Nutze einen Secret Key aus diesem Workspace mit dem Scope, den die Meldung nennt.

403 origin_not_allowed

Meldung	`This form does not accept submissions from this site.`
Ursache	Der Post kam von einer Site außerhalb der erlaubten Domains des Formulars und das Formular lehnt Abweichungen ab, oder ein Publishable Key wurde von einer Domain verwendet, die nicht beim Schlüssel eingetragen ist.
Lösung	Füge die Site zu Allowed domains oder zu den Domains des Schlüssels hinzu. Für Posts vom Server nutze einen Secret Key.

403 form_paused

Meldung	`This form is not accepting submissions right now.`
Ursache	Das Formular ist im Dashboard pausiert.
Lösung	Setze das Formular fort.

403 captcha_failed

Meldung	`The captcha check failed. Please try again.`
Ursache	Das Turnstile-Token fehlt, ist abgelaufen, wurde schon verwendet oder konnte nicht verifiziert werden.
Lösung	Hol dir für jedes Absenden ein neues Token. Bei eigenen Schlüsseln prüf, ob der Site Key zum Secret passt.

403 challenge_required

Meldung	`Complete the human check, then send the form again.`
Ursache	Das Formular nutzt die Ikiform-Menschlichkeitsprüfung und ein JSON-Post kam ohne Token an.
Lösung	Ruf `challenge(formId)` aus dem SDK auf und übergib das Token, oder nutze `error.challenge_url`. Posts vom Server können stattdessen einen Secret Key senden.

404 not_found

Meldung	`Not found.`
Ursache	Das Formular existiert nicht, wurde gelöscht oder deaktiviert, oder die ID oder Route ist falsch. Wird auch bei einem `GET` an `/f/<formId>` zurückgegeben.
Lösung	Kopiere den Endpunkt aus der Übersicht des Formulars und sende per POST, statt ihn in einem Tab zu öffnen.

405 method_not_allowed

Meldung	`This method is not allowed here.`
Ursache	Ein Browser-Preflight an die REST-API, die nur von Server zu Server funktioniert.
Lösung	Ruf `/api/v1` aus deinem Backend auf.

409 idempotency_in_progress

Meldung	`A request with this idempotency key is still being processed.`
Ursache	Ein Request mit diesem Idempotenzschlüssel wird noch verarbeitet.
Lösung	Warte einen Moment und versuch es mit demselben Schlüssel erneut; du erhältst die erste Antwort.

413 payload_too_large

Meldung	`The submission is too large.`
Ursache	Der Body, ein Feldname, ein Wert oder die Anzahl der Felder liegt über dem Limit. Die Meldung sagt, welches.
Lösung	Siehe Limits. Verteile langen Text auf mehrere Felder oder speichere Dateien woanders und sende einen Link.

415 unsupported_media_type

Meldung	`Send the form as urlencoded, multipart or JSON.`
Ursache	Der `Content-Type` ist nicht urlencoded, Multipart oder JSON, oder er fehlt.
Lösung	Setze `Content-Type: application/json`, wenn du JSON sendest.

415 unsupported_charset

Meldung	`Only UTF-8 is supported.`
Ursache	Der Body ist nicht UTF-8 oder deklariert einen anderen Zeichensatz.
Lösung	Kodiere als UTF-8. Füge alten HTML-Formularen `accept-charset="utf-8"` hinzu.

422 validation_failed

Meldung	`Some fields are invalid.`
Ursache	Felder haben die Validierung nicht bestanden. `error.fields` ordnet Feld-IDs Meldungen zu.
Lösung	Zeig die Meldungen neben den Feldern an. Siehe Felder.

422 files_not_supported

Meldung	`File uploads are not supported yet.`
Ursache	Der Post enthält eine Datei. Datei-Uploads sind noch nicht gebaut.
Lösung	Entferne Datei-Inputs, oder lade Dateien woanders hoch und sende den Link.

422 too_deep

Meldung	`The JSON body is nested too deeply.`
Ursache	Der JSON-Body ist mehr als 3 Ebenen tief verschachtelt, das Objekt auf oberster Ebene mitgezählt.
Lösung	Mach die Daten flach, zum Beispiel `{ "address_city": "London" }`.

422 idempotency_mismatch

Meldung	`This idempotency key was already used with a different payload.`
Ursache	Dieser Idempotenzschlüssel wurde für dieses Formular in den letzten 24 Stunden schon mit anderen Feldern verwendet.
Lösung	Nutze einen neuen Schlüssel für neue Daten. Behalte denselben Schlüssel nur für exakte Wiederholungen.

429 rate_limited

Meldung	`Too many requests. Please slow down.`
Ursache	Rate-Limit überschritten. `Retry-After` gibt an, wie viele Sekunden du warten sollst.
Lösung	Warte und versuch es erneut. Wenn echte Besucher darauf stoßen, ändere das Rate-Limit des Formulars.

429 quota_exceeded

Meldung	`This form isn't accepting submissions right now.`
Ursache	Der Workspace hat diesen Monat das Doppelte seines monatlichen Einsendungslimits erhalten.
Lösung	Upgrade oder warte auf den nächsten Monat. Siehe Monatliche Nutzung.

500 server_error

Meldung	`Something went wrong on our side.`
Ursache	Bei Ikiform ist etwas fehlgeschlagen.
Lösung	Versuch es mit Backoff und einem Idempotenzschlüssel erneut. Wenn es weiter passiert, gib die `request_id` an.

Keine Fehler

Spam erhält dieselbe 201 oder Weiterleitung wie eine echte Einsendung. Du findest ihn im Dashboard unter dem Spamfilter.
Ein nicht erlaubter _redirect wird ignoriert, und der Browser landet auf der gehosteten Danke-Seite.
Ein _replyto, das keine einzelne gültige E-Mail-Adresse ist, wird ignoriert.

Erneute Versuche

Versuch 429 nach Retry-After erneut, und 500, 409 oder Netzwerkfehler mit Backoff. Sende einen Idempotenzschlüssel, damit ein erneuter Versuch nie ein Duplikat erzeugt.
Versuch andere 4xx-Fehler nicht unverändert erneut. Korrigiere zuerst den Request.