Erreurs et catalogue

JSON de problèmeCopier le lien vers cette section

Toute réponse d’erreur est un JSON de problème (RFC 9457) : type, title et status, avec detail quand il y a plus à dire. Un 422 ajoute errors, une liste de constats. Chacun comporte un code du catalogue, qui le corrige (who_fixes), un fix_hint et un message, ainsi qu’un field quand le constat porte sur un seul champ (voir la page 3.2). La ligne surlignée est le code.

curl -X POST "https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0051" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/xml" \
  -H "Idempotency-Key: order-2026-0051" \
  --data-binary @not-an-invoice.xml

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.file.Path;

public class Example {
    public static void main(String[] args) throws Exception {
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0051"))
            .header("Authorization", "Bearer <your-api-key>")
            .header("Content-Type", "application/xml")
            .header("Idempotency-Key", "order-2026-0051")
            .POST(HttpRequest.BodyPublishers.ofFile(Path.of("not-an-invoice.xml")))
            .build();
        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}

import { readFile } from 'node:fs/promises';

const response = await fetch('https://api-sandbox-eu.eurinvoice.com/invoices/xml?route=PEPPOL&invoice_ref=INV-2026-0051', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <your-api-key>',
    'Content-Type': 'application/xml',
    'Idempotency-Key': 'order-2026-0051',
  },
  body: await readFile('not-an-invoice.xml'),
});
console.log(response.status);
console.log(await response.text());

{
  "type": "https://eurinvoice.com/problems/validation-failed",
  "title": "The invoice did not pass the checks",
  "errors": [
    {
      "code": "EI-XML-TYPE",
      "fix_hint": "Send the invoice itself, in the format agreed for the route.",
      "who_fixes": "erp",
      "source": "XML-safety",
      "message": "The file is not an invoice in a format this route accepts. Please send the invoice in the agreed format."
    }
  ],
  "status": 422
}

Pour un chemin que le service ne connaît pas, la réponse est 404 avec {"detail": "Not Found"}, en JSON simple.

Ce que signifie chaque statutCopier le lien vers cette section

Chaque 409 a son propre type de problème, sous https://eurinvoice.com/problems/ : idempotency-conflict, request-in-progress, already-submitted, send-in-progress, dead-letter, credential-exists et credential-revoked. Lisez le type, et non le title, pour les distinguer. Un 413 n’est pas enregistré sous la valeur de l’en-tête Idempotency-Key : la même clé peut donc être réutilisée avec un corps plus petit.

Un 429 est compté par client et par portée, avec Retry-After (voir limites). Après un 202, vous ne renvoyez jamais la facture. Les erreurs passagères côté réseau donnent lieu à de nouvelles tentatives selon notre calendrier, et un rejet définitif va sur la liste de suivi.

Qui agitCopier le lien vers cette section

Chaque code du catalogue a un seul responsable.

L’intégrateur corrige 400, 401, 403, 409, 413 et 415. Un 422 contient des constats, et chacun indique qui le corrige : erp est l’intégrateur, us est eurinvoice.

Le catalogueCopier le lien vers cette section

Le catalogue contient un code pour chaque constat. Cette page en montre un échantillon de douze, un ou deux par famille de règles. Tapez un code et appuyez sur Entrée pour y accéder. Avec une clé, GET /catalogue/{code} explique n’importe quel code (voir consulter le catalogue). Le catalogue complet est réservé aux intégrateurs : demandez-le avec l’accès au bac à sable.