Fouten en de catalogus

Problem JSONDe link naar deze sectie kopiëren

Elk foutantwoord is problem JSON (RFC 9457): type, title en status, met detail als er meer te zeggen is. Een 422 voegt errors toe, een lijst van bevindingen. Elke bevinding bevat een code uit de catalogus, de partij die ze oplost (who_fixes), een fix_hint en een message, en een field als de bevinding over één veld gaat (zie pagina 3.2). De gemarkeerde regel is de 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
}

Een pad dat de dienst niet kent, geeft 404 met {"detail": "Not Found"}, gewone JSON.

Wat elke status betekentDe link naar deze sectie kopiëren

Elke 409 heeft een eigen type in de problem JSON, onder https://eurinvoice.com/problems/: idempotency-conflict, request-in-progress, already-submitted, send-in-progress, dead-letter, credential-exists en credential-revoked. Lees het type, niet de title, om ze uit elkaar te houden. Een 413 wordt niet bij de Idempotency-Key opgeslagen, dus dezelfde sleutel kan opnieuw worden gebruikt met een kleinere body.

Een 429 komt per eindklant en scope, met Retry-After (zie limieten). Na een 202 verzendt u nooit opnieuw. Fouten aan de kant van het netwerk die vanzelf kunnen overgaan, proberen we volgens ons schema opnieuw, en een definitieve afwijzing gaat naar de opvolgingslijst.

Wie handeltDe link naar deze sectie kopiëren

Elke cataloguscode heeft één verantwoordelijke.

De partner lost 400, 401, 403, 409, 413 en 415 op. Een 422 bevat bevindingen, en elke bevinding zegt wie ze oplost: erp is de partner, us is eurinvoice.

De catalogusDe link naar deze sectie kopiëren

De catalogus bevat een code voor elke bevinding. Deze pagina toont een selectie van twaalf, een of twee per groep regels. Typ een code en druk op Enter om ernaartoe te springen. Met een sleutel legt GET /catalogue/{code} elke code uit (zie catalogus raadplegen). De volledige catalogus is voor partners: vraag hem aan met toegang tot de sandbox.