Erreurs

Chaque code d'erreur renvoyé par Ikiform, avec son statut HTTP, sa cause et sa solution.

Les soumissions de formulaire et l'API REST partagent la même enveloppe d'erreur. Les requêtes JSON la reçoivent avec le statut HTTP correspondant ; les envois de formulaire depuis un navigateur reçoivent une page d'erreur hébergée avec le même message et le même statut.

L'enveloppe d'erreur

Erreur

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

error.code est stable : basez votre logique dessus. error.message est un texte en anglais destiné aux humains et peut changer.
error.fields est présent sur les erreurs de validation, indexé par id de champ, chacun avec une liste de messages. Les erreurs qui concernent tout le corps utilisent la clé _form.
error.challenge_url est présent sur challenge_required.
request_id correspond à l'en-tête X-Request-Id présent sur chaque réponse.
Les réponses limitées en débit contiennent Retry-After en secondes. Les deux en-têtes sont lisibles depuis le code navigateur.

Codes

Statut	Code	Où
400	`invalid_body`	Envoi
400	`invalid_request`	API
401	`unauthorized`	API
402	`plan_required`	Envoi
403	`forbidden`	Les deux
403	`origin_not_allowed`	Envoi
403	`form_paused`	Envoi
403	`captcha_failed`	Envoi
403	`challenge_required`	Envoi
404	`not_found`	Les deux
405	`method_not_allowed`	API
409	`idempotency_in_progress`	Envoi
413	`payload_too_large`	Envoi
415	`unsupported_media_type`	Envoi
415	`unsupported_charset`	Envoi
422	`validation_failed`	Envoi
422	`files_not_supported`	Envoi
422	`too_deep`	Envoi
422	`idempotency_mismatch`	Envoi
429	`rate_limited`	Les deux
429	`quota_exceeded`	Envoi
500	`server_error`	Les deux

400 invalid_body

Message	`The request body could not be read.`
Cause	JSON ou multipart mal formé, tableau ou chaîne JSON au lieu d'un objet, ou clé d'idempotence de plus de 255 caractères.
Solution	Envoyez un seul objet JSON, ou laissez le navigateur ou `FormData` construire le corps.

400 invalid_request

Message	`The request is invalid.`
Cause	`limit`, `status`, `form_id` ou `cursor` est invalide. Le message indique le paramètre.
Solution	Utilisez `limit` de 1 à 100, `status` à `received` ou `spam`, un vrai id `frm_`, et les curseurs exactement tels que renvoyés.

401 unauthorized

Message	`A valid API key is required.`
Cause	Pas d'en-tête `Authorization`, pas un token Bearer, ou une clé inconnue, révoquée ou expirée.
Solution	Envoyez `Authorization: Bearer ik_sk_...` avec une clé secrète active.

402 plan_required

Message	`This form isn't accepting submissions right now.`
Cause	L'espace de travail n'a pas d'offre active. Cela ne peut arriver qu'une fois la facturation activée.
Solution	Choisissez une offre dans le tableau de bord sous Settings.

403 forbidden

Message	`You do not have access to this resource.`
Cause	La clé API est mal formée, appartient à un autre espace de travail, est une clé publiable utilisée sur l'API REST, ou n'a pas la portée nécessaire.
Solution	Utilisez une clé secrète de cet espace de travail avec la portée indiquée dans le message.

403 origin_not_allowed

Message	`This form does not accept submissions from this site.`
Cause	L'envoi vient d'un site hors des domaines autorisés du formulaire et le formulaire refuse les non-correspondances, ou une clé publiable a été utilisée depuis un domaine non listé sur la clé.
Solution	Ajoutez le site à Allowed domains ou aux domaines de la clé. Pour les envois serveur, utilisez une clé secrète.

403 form_paused

Message	`This form is not accepting submissions right now.`
Cause	Le formulaire est en pause dans le tableau de bord.
Solution	Réactivez le formulaire.

403 captcha_failed

Message	`The captcha check failed. Please try again.`
Cause	Le token Turnstile est absent, expiré, déjà utilisé, ou sa vérification a échoué.
Solution	Obtenez un nouveau token pour chaque envoi. Avec vos propres clés, vérifiez que la clé de site correspond au secret.

403 challenge_required

Message	`Complete the human check, then send the form again.`
Cause	Le formulaire utilise la vérification humaine Ikiform et un envoi JSON est arrivé sans token.
Solution	Appelez `challenge(formId)` du SDK et passez le token, ou utilisez `error.challenge_url`. Les envois serveur peuvent envoyer une clé secrète à la place.

404 not_found

Message	`Not found.`
Cause	Le formulaire n'existe pas, a été supprimé ou désactivé, ou l'id ou la route est faux. Également renvoyé pour un `GET` vers `/f/<formId>`.
Solution	Copiez l'endpoint depuis la vue d'ensemble du formulaire, et envoyez un POST au lieu de l'ouvrir dans un onglet.

405 method_not_allowed

Message	`This method is not allowed here.`
Cause	Un preflight de navigateur sur l'API REST, qui fonctionne uniquement de serveur à serveur.
Solution	Appelez `/api/v1` depuis votre backend.

409 idempotency_in_progress

Message	`A request with this idempotency key is still being processed.`
Cause	Une requête avec cette clé d'idempotence est encore en cours de traitement.
Solution	Attendez un instant et réessayez avec la même clé ; vous recevrez la première réponse.

413 payload_too_large

Message	`The submission is too large.`
Cause	Le corps, un nom de champ, une valeur ou le nombre de champs dépasse sa limite. Le message indique lequel.
Solution	Voir Limites. Répartissez les longs textes sur plusieurs champs, ou stockez les fichiers ailleurs et envoyez un lien.

415 unsupported_media_type

Message	`Send the form as urlencoded, multipart or JSON.`
Cause	Le `Content-Type` n'est ni urlencoded, ni multipart, ni JSON, ou il est absent.
Solution	Définissez `Content-Type: application/json` quand vous envoyez du JSON.

415 unsupported_charset

Message	`Only UTF-8 is supported.`
Cause	Le corps n'est pas en UTF-8, ou déclare un autre charset.
Solution	Encodez en UTF-8. Ajoutez `accept-charset="utf-8"` aux anciens formulaires HTML.

422 validation_failed

Message	`Some fields are invalid.`
Cause	Des champs ont échoué à la validation. `error.fields` associe les ids de champs à des messages.
Solution	Affichez les messages à côté des champs. Voir Champs.

422 files_not_supported

Message	`File uploads are not supported yet.`
Cause	L'envoi contient un fichier. L'envoi de fichiers n'existe pas encore.
Solution	Retirez les inputs de fichier, ou téléversez les fichiers ailleurs et envoyez le lien.

422 too_deep

Message	`The JSON body is nested too deeply.`
Cause	Le corps JSON est imbriqué sur plus de 3 niveaux, en comptant l'objet racine.
Solution	Aplatissez les données, par exemple `{ "address_city": "London" }`.

422 idempotency_mismatch

Message	`This idempotency key was already used with a different payload.`
Cause	Cette clé d'idempotence a déjà été utilisée pour ce formulaire dans les dernières 24 heures avec des champs différents.
Solution	Utilisez une nouvelle clé pour de nouvelles données. Ne gardez la même clé que pour les nouvelles tentatives à l'identique.

429 rate_limited

Message	`Too many requests. Please slow down.`
Cause	Limite de débit dépassée. `Retry-After` indique combien de secondes attendre.
Solution	Attendez et réessayez. Si de vrais visiteurs l'atteignent, modifiez la limite de débit du formulaire.

429 quota_exceeded

Message	`This form isn't accepting submissions right now.`
Cause	L'espace de travail a reçu ce mois-ci 2 fois sa limite mensuelle de soumissions.
Solution	Passez au palier supérieur, ou attendez le mois suivant. Voir Usage mensuel.

500 server_error

Message	`Something went wrong on our side.`
Cause	Une erreur s'est produite du côté d'Ikiform.
Solution	Réessayez avec un backoff et une clé d'idempotence. Si le problème persiste, indiquez le `request_id`.

Ce qui n'est pas une erreur

Le spam reçoit le même 201 ou la même redirection qu'une vraie soumission. Cherchez-le sous le filtre spam du tableau de bord.
Un _redirect non autorisé est ignoré, et le navigateur arrive sur la page de remerciement hébergée.
Un _replyto qui n'est pas une seule adresse e-mail valide est ignoré.

Réessayer

Réessayez un 429 après Retry-After, et les 500, 409 ou erreurs réseau avec un backoff. Envoyez une clé d'idempotence pour qu'une nouvelle tentative ne crée jamais de doublon.
Ne réessayez pas les autres erreurs 4xx sans rien changer. Corrigez d'abord la requête.