Référence des codes d'erreur

Cette page est la référence centralisée pour les réponses d’erreur de toutes les API fiskaly. Utilisez l’explorateur interactif ci-dessous pour rechercher et filtrer les erreurs, ou faites défiler vers le bas pour consulter les tableaux de référence statiques.

36 errors found

Référence statique

Commencez par l’arbre de décision de dépannage si vous avez une erreur et avez besoin d’une réponse rapide, ou consultez les tableaux spécifiques aux produits pour les codes d’erreur détaillés.

Format de réponse d’erreur

Toutes les API fiskaly retournent les erreurs dans un format JSON cohérent :

{
  "status_code": 400,
  "error": "Bad Request",
  "code": "E_SOME_ERROR",
  "message": "Une description lisible de ce qui s'est mal passé"
}

Champ	Type	Description
`status_code`	entier	Code de statut HTTP
`error`	chaîne	Texte de statut HTTP
`code`	chaîne	Code d’erreur spécifique à fiskaly (préfixé par `E_`)
`message`	chaîne	Description de l’erreur lisible par l’humain

Codes de statut HTTP

2xx — Succès

Code	Signification	Quand vous le voyez
`200`	OK	La requête a réussi ; le corps de la réponse contient le résultat
`201`	Créé	Ressource créée avec succès
`204`	Pas de contenu	La requête a réussi, pas de corps de réponse (ex. opérations DELETE)

4xx — Erreurs client

Celles-ci indiquent un problème avec votre requête. Ne pas réessayer avec le même payload — corrigez d’abord le problème.

Code	Signification	Causes courantes
`400`	Requête incorrecte	JSON malformé, champs obligatoires manquants, valeurs de champ invalides
`401`	Non autorisé	Token d’accès expiré ou manquant, identifiants API invalides
`403`	Interdit	Permissions insuffisantes pour la ressource demandée
`404`	Non trouvé	La ressource n’existe pas, ou chemin URL incorrect
`409`	Conflit	La ressource existe déjà (tentative de création en double)
`422`	Entité non traitable	JSON valide mais sémantiquement incorrect (ex. transition d’état invalide)
`423`	Verrouillé	La ressource est actuellement verrouillée par une autre opération
`429`	Trop de requêtes	Limite de fréquence dépassée — reculez et réessayez avec un délai exponentiel

5xx — Erreurs serveur

Celles-ci indiquent un problème temporaire du côté de fiskaly. Sûr à réessayer avec backoff exponentiel.

Code	Signification	Action
`500`	Erreur interne du serveur	Réessayez après un court délai ; si persistant, vérifiez status.fiskaly.com
`502`	Mauvaise passerelle	Service amont temporairement indisponible ; réessayez
`503`	Service indisponible	Le service est temporairement en maintenance ; réessayez
`504`	Délai de passerelle dépassé	La requête a expiré en amont ; réessayez avec un timeout plus long

Erreurs d’authentification

Ce sont les erreurs les plus courantes rencontrées par les développeurs lors de l’intégration.

Code d’erreur	Statut HTTP	Cause	Solution
`E_UNAUTHORIZED_ACCESS`	401	Token d’accès expiré ou non fourni	Ré-authentifiez-vous en utilisant votre clé et secret API
`E_INVALID_CREDENTIALS`	401	La clé ou le secret API est incorrect	Vérifiez les identifiants dans le HUB
`E_TOKEN_EXPIRED`	401	Le token d’accès JWT a expiré	Utilisez le token de rafraîchissement ou ré-authentifiez-vous
`E_ACCESS_FORBIDDEN`	403	Votre clé API n’a pas la permission pour cette ressource	Vérifiez les portées de la clé API dans le HUB

Cycle de vie du token

Clé API + Secret  →  POST /auth  →  access_token (24h) + refresh_token (48h)
                                         │
                                         ├── Utiliser pour tous les appels API
                                         │
                                         └── Sur 401 → ré-authentifier (pas à chaque requête)

💡Ne vous ré-authentifiez pas à chaque requête

Le token d’accès est valable 24 heures et le token de rafraîchissement 48 heures. Se ré-authentifier à chaque requête ajoute une latence inutile à votre processus de paiement. Mettez le token en cache et ne le rafraîchissez que lorsque vous recevez une réponse 401.

SIGN DE — Erreurs TSS

Code d’erreur	Statut HTTP	Cause	Solution
`E_TSS_NOT_FOUND`	404	L’ID TSS n’existe pas	Vérifiez l’ID TSS ; listez tous les TSS via `GET /tss`
`E_TSS_NOT_INITIALIZED`	400	Le TSS n’a pas encore été initialisé	Suivez toutes les étapes nécessaires : créer le TSS, le mettre à `UNINITIALIZED`, définir le PIN Admin, se connecter en tant qu’Admin et mettre le TSS à `INITIALIZED`
`E_TSS_DISABLED`	400	Le TSS a été désactivé	Le TSS ne peut plus signer de transactions ; créez un nouveau TSS
`E_TSS_IN_USE`	409	Le TSS est en cours de modification par une autre requête	Attendez et réessayez
`E_CLIENT_NOT_FOUND`	404	L’ID client n’existe pas pour ce TSS	Créez un client via `PUT /tss/{tss_id}/client/{client_id}`
`E_CLIENT_NOT_REGISTERED`	400	Le client existe mais n’est pas enregistré	Enregistrez le client avant de créer des transactions
`E_TX_NOT_FOUND`	404	L’ID de transaction n’existe pas	Vérifiez l’ID de transaction et le contexte TSS
`E_TX_INVALID_STATE`	422	La transaction est dans un état qui ne permet pas cette opération	Vérifiez l’état actuel de la transaction ; suivez la machine à états
`E_EXPORT_NOT_FOUND`	404	L’ID d’export n’existe pas	Vérifiez l’ID d’export ; les exports peuvent prendre du temps à traiter
`E_EXPORT_IN_PROGRESS`	409	L’export est encore en cours de génération	Interrogez l’état de l’export jusqu’à `state: COMPLETED`

Erreurs SUBMIT DE

Code d’erreur	Statut HTTP	Cause	Solution
`E_ESTABLISHMENT_NOT_FOUND`	404	ID d’établissement non trouvé	Vérifiez que l’établissement existe pour votre organisation
`E_TAXPAYER_NOT_FOUND`	404	Enregistrement du contribuable non trouvé	Créez d’abord la ressource contribuable
`E_TAXPAYER_ADDRESS_NOT_FOUND`	404	Adresse du contribuable non configurée	Ajoutez des données d’adresse à la ressource contribuable
`E_TAXPAYER_PERSON_NOT_FOUND`	404	Enregistrement de personne du contribuable manquant	Ajoutez des données de personne à la ressource contribuable
`E_SUBMISSION_NOT_FOUND`	404	ID de déclaration non trouvé	Vérifiez l’ID de déclaration ; vérifiez que la déclaration a été créée
`E_CLIENT_ADDITIONAL_DATA_NOT_FOUND`	404	Données supplémentaires du client manquantes	Fournissez les données supplémentaires requises pour le client
`E_LOCKED_RESOURCE`	423	La ressource est verrouillée par une opération en cours	Attendez la fin de l’opération en cours, puis réessayez

Erreurs DSFINVK DE

Code d’erreur	Statut HTTP	Cause	Solution
`E_CASH_REGISTER_NOT_FOUND`	404	Caisse enregistreuse non trouvée	Créez d’abord la caisse enregistreuse via l’API DSFinV-K
`E_CASH_POINT_CLOSING_NOT_FOUND`	404	Clôture de point de vente non trouvée	Vérifiez l’ID de clôture
`E_VAT_DEFINITION_NOT_FOUND`	404	Définition de TVA non configurée	Créez les définitions de TVA avant d’insérer des clôtures
`E_INVALID_CLOSING_DATA`	400	Le payload de clôture ne correspond pas au schéma attendu	Validez votre payload par rapport à la spécification DSFinV-K

API Unifiée — Erreurs communes

Ces erreurs sont partagées par tous les produits de l’API Unifiée (SIGN FR, SIGN IT, SIGN ES).

Code d’erreur	Statut HTTP	Cause	Solution
`E_ORGANIZATION_NOT_FOUND`	404	L’ID organisation n’existe pas	Vérifiez l’ID org ; assurez-vous qu’elle a été créée sous le bon GROUP
`E_TAXPAYER_NOT_COMMISSIONED`	400	Le contribuable existe mais son état n’est pas `COMMISSIONED`	Mettez à jour l’état du contribuable à `COMMISSIONED` avant les opérations
`E_IDEMPOTENCY_KEY_REUSED`	409	La clé d’idempotence a déjà été utilisée pour une autre requête	Générez un nouveau UUID pour chaque nouvelle requête
`E_API_VERSION_NOT_SUPPORTED`	400	L’header `X-Api-Version` contient une date non supportée	Utilisez la dernière version supportée (ex. `2026-02-03`)
`E_SCOPE_IDENTIFIER_MISSING`	400	Header `X-Scope-Identifier` non fourni	Incluez l’ID d’organisation dans `X-Scope-Identifier`
`E_SUBJECT_NOT_FOUND`	404	Subject (clé API) non trouvé	Vérifiez que le subject a été créé sous la bonne organisation
`E_TOKEN_INVALID`	401	Le token est malformé ou expiré	Ré-authentifiez-vous via `POST /api/v1/auth/token`
`E_LOCATION_NOT_COMMISSIONED`	400	L’emplacement existe mais n’est pas commissionné	Mettez à jour l’état de l’emplacement à `COMMISSIONED`
`E_SYSTEM_NOT_COMMISSIONED`	400	Le système existe mais n’est pas commissionné	Mettez à jour l’état du système à `COMMISSIONED`

💡Clés d'idempotence sur toutes les API Unifiées

Tous les produits de l’API Unifiée supportent l’header X-Idempotency-Key sur les requêtes mutantes. Les paires clé-valeur expirent après 24 heures. Si vous réutilisez une clé avec un payload différent, vous recevrez un 422 Unprocessable Entity. Si la requête originale est encore en cours de traitement, vous recevrez un 409 Conflict.

SIGN FR — Erreurs spécifiques

Code d’erreur	Statut HTTP	Cause	Solution
`E_RECORD_INVALID_OPERATION`	422	Le type d’opération du record n’est pas valide pour l’état actuel	Vérifiez le flux Intention → Transaction ; assurez la bonne séquence
`E_RECORD_INTENTION_REQUIRED`	400	Record de transaction créé sans Intention préalable	Créez d’abord un record Intention, puis référencez son ID
`E_TAXPAYER_CREDENTIALS_INVALID`	400	Les identifiants de fiscalisation française (NF 525) sont invalides	Vérifiez `tax_id_number` (SIREN) et les identifiants
`E_CLOSURE_IN_PROGRESS`	409	Une clôture fiscale est déjà en cours	Attendez la fin de la clôture en cours

SIGN IT — Erreurs spécifiques

Code d’erreur	Statut HTTP	Cause	Solution
`E_RT_DEVICE_NOT_FOUND`	404	Dispositif Registratore Telematico non trouvé	Vérifiez que le dispositif RT a été créé et commissionné
`E_RT_SUBMISSION_FAILED`	502	Envoi à Agenzia delle Entrate échoué	Réessayez ; vérifiez l’état du service AdE si persistant
`E_LOTTERY_CODE_INVALID`	400	Le format du code de la loterie des reçus est invalide	Assurez-vous que le code de la loterie comporte 8 caractères alphanumériques
`E_FISCAL_CODE_INVALID`	400	Le format du codice fiscale italien est incorrect	Vérifiez le format du code fiscal à 16 caractères

SIGN ES — Erreurs de validation

SIGN ES retourne les erreurs de validation dans un tableau validations dans la réponse, chacune avec un code et une description. Celles-ci sont spécifiques aux transmissions TicketBAI / Verifactu / SII.

Code de validation	Cause
`V_TICKETBAI`	Erreur inconnue ou non gérée de TicketBAI
`V_XSD_SCHEMA_NOT_COMPLY`	Le fichier XML n’est pas conforme au schéma XML
`V_INVOICE_WITHOUT_LINES`	Le fichier XML n’inclut pas de lignes de détail
`V_REQUIRED_FIELD_MISSING_OR_INCORRECT`	Des données obligatoires sont manquantes ou incorrectes
`V_INVOICE_ALREADY_REGISTERED`	Une facture avec le même numéro/série/année était déjà enregistrée
`V_SERVICE_NOT_AVAILABLE`	Le service de réception n’est pas disponible
`V_INCORRECT_SENDER_CERTIFICATE`	Le certificat de l’expéditeur est inconnu
`V_INVALID_SENDER_CERTIFICATE`	Le certificat de l’expéditeur n’est pas valide
`V_WRONG_SIGNATURE`	La validation de la signature a échoué
`V_INCORRECT_INVOICE_CHAINING`	L’enchaînement des factures était incorrect
`V_INVALID_TBAI_LICENSE`	Licence TicketBAI non enregistrée ou non valide
`V_DEVICE_NOT_REGISTERED`	Le certificat de dispositif utilisé pour l’envoi est en attente d’enregistrement
`V_EXPIRED_SIGNATURE_CERTIFICATE`	Le certificat utilisé pour signer le fichier TicketBAI a expiré
`V_EXPIRED_SENDER_CERTIFICATE`	Le certificat de l’expéditeur n’est pas valide ou a expiré
`V_EXPIRED_SIGNER_CERTIFICATE`	Le certificat utilisé pour la signature n’est pas valide ou a expiré
`V_FULL_AMOUNT_MISMATCH`	La somme des `full_amount` des lignes n’est pas égale au `full_amount` de la facture
`V_ISSUE_DATE_OUT_OF_RANGE`	La date d’émission a plus de 20 ans ou est dans le futur
`V_INVALID_VAT_RATE`	Le taux de TVA n’est pas une valeur valide pour la région du contribuable
`V_INVOICE_ALREADY_CANCELLED`	La facture a déjà été annulée
`V_INVOICE_ALREADY_CORRECTED`	La facture a déjà été corrigée
`V_INCOMPATIBLE_VAT_SYSTEMS`	Les systèmes de TVA fournis ne sont pas compatibles entre eux
`V_INCORRECT_ITEM_VAT_CALCULATION`	Un article de la facture a un calcul de TVA appliqué de manière incorrecte

📘Les erreurs de validation de SIGN ES ne sont pas bloquantes

Les erreurs de validation apparaissent dans le tableau validations de la réponse mais ne empêchent pas nécessairement la création du record. Vérifiez le champ state du record (REJECTED ou FAILED) pour déterminer si l’erreur était fatale.

Recommandations de timeout

Les différentes opérations ont des durées attendues différentes. Configurez vos timeouts en conséquence :

Opération	Timeout recommandé	Notes
Authentification (`POST /auth`)	3-4 secondes	Opération rapide ; ne pas bloquer le paiement
Signature de transaction (`PUT /tx`)	3-5 secondes	Ne devrait jamais bloquer la caisse
Création / initialisation TSS	30 secondes	Configuration unique ; traitement plus lourd
Clôtures de point de vente DSFinV-K	Jusqu’à 10 minutes	Traitement lourd avec de grands jeux de données
Génération d’export	Basée sur polling	Utilisez le polling asynchrone, pas l’attente synchrone

⚠️Ne bloquez jamais le paiement

Définissez les timeouts de signature de transactions entre 3 et 5 secondes. Une signature manquante ne rend pas un reçu non conforme (voir AEAO au 146a, Point 7). Ajoutez une note comme “TSS non disponible” aux reçus non signés et incluez-les dans l’export DSFinV-K.

💡Rendez les timeouts configurables

Permettez aux administrateurs d’ajuster les valeurs de timeout (ex. 1,5-5 secondes pour les transactions) sans modification de code. Cela économise des cycles de développement et s’adapte aux conditions de réseau variables.

Stratégie de retry

Pour les erreurs transitoires (5xx, timeouts, limites de fréquence), utilisez le backoff exponentiel :

async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxRetries) throw error;

      const isRetryable =
        error.status >= 500 ||
        error.status === 429 ||
        error.code === "ETIMEDOUT";

      if (!isRetryable) throw error;

      const delay = Math.min(1000 * 2 ** attempt, 30000);
      await new Promise((r) => setTimeout(r, delay));
    }
  }
}

Arbre de décision de dépannage

Vous avez une erreur ?
  │
  ├── 401 Unauthorized
  │     └── Votre token a-t-il expiré ?
  │           ├── Oui → Ré-authentifiez-vous avec clé API + secret
  │           └── Non → Vérifiez les identifiants dans le HUB
  │
  ├── 400 Bad Request
  │     └── Vérifiez le champ `message` pour savoir quel champ est invalide
  │           └── Validez votre payload JSON par rapport au schéma API
  │
  ├── 404 Not Found
  │     └── La ressource existe-t-elle ?
  │           ├── Vérifiez que l'ID est correct (format UUIDv4)
  │           └── Assurez-vous que la ressource a été créée dans le bon environnement (TEST vs LIVE)
  │
  ├── 409 Conflict
  │     └── La ressource existe déjà ou est en cours de modification
  │           └── Utilisez GET pour vérifier l'état actuel avant de réessayer
  │
  ├── 429 Rate Limited
  │     └── Reculez avec un délai exponentiel
  │           └── Vérifiez si vous vous ré-authentifiez à chaque requête (ne le faites pas)
  │
  └── Erreur 5xx du serveur
        └── Vérifiez status.fiskaly.com
              ├── Incident connu → Attendez la résolution
              └── Pas d'incident → Réessayez avec backoff exponentiel ; contactez le support si persistant

État du service

Surveillez l’état du service fiskaly sur status.fiskaly.com.

Erreurs d’intégration courantes

Ce sont les erreurs que le support fiskaly voit le plus souvent de la part des équipes lors de leur première intégration. Les éviter économise un temps de débogage significatif.

Erreur	Ce qui se passe	Comment l’éviter
Se ré-authentifier à chaque requête	Erreurs de limite de fréquence `429` ; latence inutile à chaque paiement	Mettez en cache le token d’accès (TTL 24h). Ré-authentifiez-vous seulement sur `401`.
Ne pas sauvegarder le `admin_puk`	Impossible de définir le PIN Admin sur le TSS ; bloqué en état `UNINITIALIZED`	Sauvegardez le `admin_puk` de la réponse de création du TSS immédiatement.
Réutiliser des UUIDs	Erreurs `409 Conflict` lors de la création de TSS, clients ou transactions	Générez un nouveau UUIDv4 pour chaque appel de création de ressource.
Bloquer le paiement sur un échec de signature	Les clients attendent indéfiniment si le TSS est lent ou indisponible	Définissez un timeout de 3-5 secondes sur la signature. Émettez le reçu avec “TSS non disponible” et réessayez plus tard.
Utiliser des identifiants TEST en LIVE (ou vice versa)	`401 Unauthorized` — les identifiants sont spécifiques à l’environnement	Vérifiez que l’URL de base correspond à l’environnement de la clé API. TEST et LIVE sont complètement séparés.
Passer l’initialisation du TSS	`400 E_TSS_NOT_INITIALIZED` lors de la création de clients ou de transactions	Suivez toutes les étapes nécessaires : créer le TSS, le mettre à `UNINITIALIZED`, définir le PIN Admin, se connecter en tant qu’Admin et mettre le TSS à `INITIALIZED`.
Ne pas gérer correctement `tx_revision`	`422 E_TX_INVALID_STATE` ou erreurs de transaction en double	Commencez avec `tx_revision=1` (ACTIVE), finissez avec `tx_revision=2` (FINISHED). Incrémentez toujours.
Polling synchrone des exports	Timeouts sur la génération d’exports DSFinV-K (peut prendre jusqu’à 10 minutes)	Utilisez le polling asynchrone : déclenchez l’export, puis interrogez l’endpoint de statut jusqu’à `state: COMPLETED`.
Hardcoder les timeouts	L’équipe de développement ne peut pas les ajuster sans une release de code	Rendez les timeouts configurables (ex. 1,5-5 secondes pour les transactions). Ajustable par l’administrateur est l’idéal.

Ressources connexes

Guide de gestion des erreurs

Bonnes pratiques pour le timeout et la récupération des erreurs dans SIGN DE

Erreurs de déclaration

Codes d'erreur et codes de statut spécifiques à SUBMIT DE

Référence API

Documentation complète des endpoints pour toutes les API fiskaly

Was this page helpful?