Fehler & Limits

Statuscodes

Code	Bedeutung	Wiederholen?
`200`	OK — Anfrage erfolgreich	—
`201`	Erstellt — ein Datensatz wurde angelegt	—
`202`	Angenommen — ein Stapel wurde als Import-Job angelegt; fragen Sie `GET /api/v1/import-jobs/{jobId}` ab	—
`400`	Ungültige Anfrage — ungültige Eingabe oder Validierungsfehler	Nein — Anfrage korrigieren
`401`	Nicht autorisiert — der API-Schlüssel ist ungültig oder abgelaufen	Nein — Schlüssel korrigieren
`403`	Zugriff verweigert — dem Schlüssel fehlt die Berechtigung, das Modul ist nicht aktiviert, Exporte sind für Ihren Arbeitsbereich abgeschaltet (`code: "EXPORTS_BLOCKED"` bei Downloads), oder die Kontoeinrichtung ist unvollständig	Nein
`404`	Nicht gefunden — der Datensatz existiert nicht oder gehört zu einem anderen Unternehmen (bei Nachweisen und Parzellen-Verknüpfungen zu einem Lieferantenartikel: `403`)	Nein
`409`	Konflikt — der Datensatz kollidiert mit vorhandenen Daten, Ihr Parzellen-Limit ist erreicht (`PLOT_LIMIT_REACHED`), oder eine Bestätigung ist nötig (`warnings`, `overwriteRequired`)	Nein — Anfrage ändern
`413`	Anfrage zu groß — ein asynchroner Stapel (`articles`, `suppliers`, `orders`, `ppwr/quantities`) überschreitet 5.000 Zeilen (`batchTooLarge`, mit `maxBatchSize`); es wird nichts angelegt	Nein — Stapel aufteilen
`422`	Nicht verarbeitbar — die Anfrage ist korrekt, kann aber noch nicht ausgeführt werden: eine PPWR-Mengenmeldung ist nicht meldefähig (`blockingErrors`), eine DDS-Erklärung ist durch die Compliance-Prüfung blockiert (`compliance_blocked`, `details.blockingArticles`), oder ein PDF lässt sich nicht erzeugen	Nein — Daten korrigieren
`423`	Gesperrt — die hochgeladene Datei hat die Virenprüfung nicht bestanden (`scan_blocked`)	Nein
`429`	Zu viele Anfragen — das Rate-Limit ist erreicht, oder die Anfrage hatte keinen API-Schlüssel	Nur die JSON-Variante
`500`	Interner Serverfehler — meist ein Fehler auf unserer Seite	Einige Male — siehe Wiederholungen
`502` `503` `504`	Gateway- oder Timeout-Fehler	Ja

Fehlerformat

Fehler sind JSON mit einem error-Feld. Je nach Endpunkt kommen weitere Felder hinzu:

{
  "error": "Validation failed",
  "details": [
    { "code": "too_small", "path": ["address", "street"], "message": "Address is required." }
  ]
}

Feld	Inhalt
`error`	Ein String — ein lesbarer Satz oder ein stabiler Schlüssel (siehe unten)
`details`	Optional, bei einem `400`-Validierungsfehler: eine Liste von Problemen, eines je fehlerhaftem Feld — `path` (das Feld, als Liste von Schlüsseln), `message`, `code`, je nach Problem mit weiteren Schlüsseln
`warnings`	Optional, nur bei `409`: bestätigbare Warnungen, z. B. beim Anlegen eines Artikels
`code`	Optional: ein stabiler Code, z. B. bei Geometrie- und Annahmefehlern der Parzellen-Endpunkte oder `EXPORTS_BLOCKED` bei Downloads

Die einzige Ausnahme: Beim 429 des Rate-Limits ist error ein Objekt, kein String — siehe Rate-Limit.

Schlüssel oder Sätze

Stabile Schlüssel. An diesen Stellen steht ein stabiler, nicht lokalisierter Schlüssel: 413 batchTooLarge, 409 overwriteRequired, failed[].error und invalid[].error in den Ergebnissen der synchronen PPWR-Endpunkte, failed[].error.key in den Ergebnissen asynchroner Jobs sowie error des Jobs (ein Schlüssel oder ein JSON-String, dessen Feld key der stabile Teil ist). Die Parzellen-Endpunkte senden bei Geometrie- und Annahmefehlern neben dem Satz einen stabilen code. Werten Sie diese aus. Fehler im Format der Anfrage und Validierungs-400 tragen einen englischen Satz, auch bei Stapelimporten und PPWR — entscheiden Sie dort anhand des Statuscodes. Die Listen: Fehlerschlüssel Stapelimport, Fehlerschlüssel PPWR, Fehlercodes Parzellen.
Sätze. Bei den übrigen Endpunkten (z. B. beim Anlegen eines einzelnen Artikels, Lieferanten oder einer Bestellung) ist error ein englischer Satz. Sein Wortlaut kann sich ändern — entscheiden Sie anhand des Statuscodes (und warnings[].type) und protokollieren Sie den Satz.

Rate-Limit

Alle /api-Pfade teilen sich ein Limit: 1000 Anfragen pro 60 Sekunden je Client-IP-Adresse (festes Zeitfenster). Es greift, bevor die Anfrage die Anwendung erreicht. Ein separates Limit je Schlüssel gibt es nicht. Über dem Limit erhalten Sie 429 mit einem JSON-Body, dessen error ein Objekt ist:

{ "error": { "code": "rate_limited", "message": "…" } }

Ein Retry-After-Header ist nicht garantiert. Warten Sie bis zur nächsten Minute und wiederholen Sie dann mit exponentiellem Backoff und Jitter.
Das Limit zählt je IP-Adresse, nicht je Schlüssel. Alle Aufrufe von einer Büro- oder Server-IP teilen es sich — auch Personen, die die Web-App aus demselben Netz nutzen.
Verteilen Sie geplante Jobs über die Zeit, und nutzen Sie Stapel-Endpunkte statt einer Anfrage je Datensatz.

Anfragen ohne API-Schlüssel

Eine Anfrage ohne Authorization: Bearer …-Header erreicht die API nie. Der Bot-Schutz antwortet mit einer HTML-Prüfseite und Status 429. 429 mit HTML-Body beim ersten Test bedeutet also fast immer: Der Header fehlt oder ist fehlerhaft. Der Wert muss mit Bearer beginnen. Nicht wiederholen — den Header korrigieren.

Wiederholungen

Situation	Wiederholen?	Wie
`429` mit JSON `rate_limited`	Ja	Ab der nächsten Minute, mit exponentiellem Backoff und Jitter
`429` mit HTML-Seite	Nein	Den Header `Authorization: Bearer …` senden
`500`, `502`, `503`, `504`, Netzwerk-Timeout	Ja	Exponentieller Backoff mit Jitter, nach einigen Versuchen aufhören; prüfen Sie unten, ob der Aufruf gefahrlos wiederholt werden kann
`400`, `401`, `403`, `404`, `409`, `413`, `422`, `423`	Nein	Zuerst die Anfrage ändern

Ein 500 bedeutet meist einen Fehler auf unserer Seite. Scheitert dieselbe Anfrage immer wieder, liegt die Ursache wahrscheinlich in der Anfrage selbst — hören Sie auf und prüfen Sie sie. Ein einzelnes POST /api/v1/orders, dessen orderNumber bereits existiert, antwortet mit 409, ebenso ein PATCH /api/v1/orders/{id}, der die Bestellnummer auf eine bereits vorhandene ändert. Ob eine Wiederholung ein Duplikat erzeugen kann, hängt vom Endpunkt ab:

Aufruf	Gefahrlos wiederholbar?
Stapelimporte (`POST` Artikel, Lieferanten, Bestellungen als Array; `POST /api/v1/ppwr/quantities`)	Ja — Zeilen werden über ihren Schlüssel abgeglichen; vorhandene kommen als übersprungen oder aktualisiert zurück. Siehe Stapelimport
PPWR-Stammdaten (`components`, `units`, `formats`, `links`, `article-links`)	Ja — außer Einheiten-Zeilen ohne `internalRef`, die jedes Mal eine neue Einheit anlegen. Siehe PPWR
`POST /api/v1/articles` mit einem Objekt	Ja — eine Wiederholung antwortet `409`, weil die `internalArticleNr` existiert. Den Artikel finden Sie mit `GET /api/v1/articles?internalArticleNr=…`
`POST /api/v1/suppliers` mit einem Objekt	Ja — eine Wiederholung antwortet `409` (gleicher Name oder gleiche `externalSupplierId`)
`POST /api/v1/orders` mit einem Objekt	Ja — eine Wiederholung antwortet `409`, weil die `orderNumber` existiert. Prüfen Sie vor dem erneuten Senden mit `GET /api/v1/orders?orderNumbers=<Nr>`, ob die Bestellung existiert, oder senden Sie sie als Stapel mit einer Zeile (abgeglichen über `orderNumber`)
`POST /api/v1/plots`	Ja — dieselbe Parzelle wird erkannt und mit `"deduplicated": true` beantwortet. Siehe Idempotenz
`POST /api/v1/ppwr/documents`	Siehe Duplikate und Wiederholungen
`DELETE /api/v1/suppliers/{id}`	Ja — eine id, die keinen aktiven Lieferanten Ihres Unternehmens bezeichnet, antwortet `200` und löscht nichts

Anfrage-Referenz (`x-vercel-id`)

Jede Antwort trägt einen x-vercel-id-Header. Er bezeichnet genau diese eine Anfrage. Wenn Sie den Support unter help@polygon-one.eu kontaktieren, nennen Sie:

den Wert von x-vercel-id,
den Zeitpunkt der Anfrage (mit Zeitzone),
Methode und Pfad (z. B. POST /api/v1/orders).

Protokollieren Sie den Header bei jedem fehlgeschlagenen Aufruf, damit Sie ihn im Bedarfsfall haben.

Limits

Limit	Wert
Rate-Limit	1000 Anfragen pro 60 Sekunden je Client-IP, alle `/api`-Pfade
Anfrage-Body	~4,5 MB (Plattform-Limit, greift vor der Anwendung)
Asynchroner Stapel (`articles`, `suppliers`, `orders`, `ppwr/quantities`)	5.000 Zeilen pro Anfrage; darüber `413 batchTooLarge` mit `maxBatchSize: 5000`
Synchroner Stapel (PPWR-Stammdaten, `ppwr/tonnage`)	1.000 Zeilen pro Anfrage; eine Einheiten-Anfrage zusätzlich höchstens 1.000 `sizes`-Einträge insgesamt. Darüber ist die Antwort `400` mit `error` `"Too many rows: max 1000 per request"` bzw. `"Too many sizes: max 1000 per request"` (nicht `413`); es wird nichts geschrieben
Listen-Endpunkte	100 Zeilen ohne `limit`; `limit` höchstens 1000; mit `offset` blättern, bis eine Seite kürzer als `limit` ist. Eine Gesamtzahl gibt es nicht. Ausnahme: `GET /api/v1/evidence` liefert ohne `limit` und `offset` alle Zeilen
EUDR-Nachweise	bis 10 MB über `POST /api/v1/evidence/upload-url` (der `PUT` sendet genau `fileSize` Bytes); das direkte Feld `file` nimmt höchstens 4 MB an (größer → `400`)
PPWR-Dokumente	PDF, JPEG oder PNG, höchstens 10 MB (der `PUT` sendet genau `fileSize` Bytes, sonst `403`); Upload innerhalb von 10 Minuten nach Anforderung der URL
Parzellengeometrie	höchstens 250 Teile, 20.000 Punkte, 100.000 ha, 1,0° Ausdehnung je Achse — siehe Fehlercodes
Import-Jobs	die Eingabe wird ~24 Stunden nach Abschluss gelöscht; der Job-Datensatz ~30 Tage nach Erstellung gelöscht

Zeitstempel sind ISO 8601 (z. B. 2026-10-05T08:00:00.000Z). Datensatz-ids sind UUIDs. Listen sind reine JSON-Arrays, außer bei GET /api/v1/evidence ({ "evidence": [...] }).

Nicht in v1

Folgendes ist in v1 nicht verfügbar. Jede inkompatible Änderung erscheint als /api/v2/ mit mindestens sechs Monaten Parallelbetrieb (siehe Versionierung).

Cursor-Paging und Gesamtzahlen — blättern Sie mit limit und offset.
Webhooks — Integrationen fragen ab (z. B. changedSince bei Bestellungen, Status von Import-Jobs).
Eine Sandbox-Umgebung — jeder Aufruf wirkt auf Ihren Live-Arbeitsbereich.
Offizielle SDKs — erzeugen Sie einen Client aus der OpenAPI-Spezifikation.

API-Dokumentation

Artikel

Lieferanten

Parzellen

Nachweise

Bestellungen

Import-Jobs

DDS-Erklärungen

PPWR – Verpackungsdaten

PPWR – Dokumente

PPWR – Konformitätserklärungen

PPWR – Mengen & Mengenmeldung

Statuscodes

Fehlerformat

Schlüssel oder Sätze

Rate-Limit

Anfragen ohne API-Schlüssel

Wiederholungen

Anfrage-Referenz (`x-vercel-id`)

Limits

Nicht in v1

​Statuscodes

​Fehlerformat

​Schlüssel oder Sätze

​Rate-Limit

​Anfragen ohne API-Schlüssel

​Wiederholungen

​Anfrage-Referenz (x-vercel-id)

​Limits

​Nicht in v1

Statuscodes

Fehlerformat

Schlüssel oder Sätze

Rate-Limit

Anfragen ohne API-Schlüssel

Wiederholungen

Anfrage-Referenz (`x-vercel-id`)

Limits

Nicht in v1