> ## Documentation Index
> Fetch the complete documentation index at: https://help.polygon-one.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fehler & Limits

> Statuscodes, Fehlerformat, Rate-Limit, Wiederholungen und Größenlimits der Polygon One API

## 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](#rate-limit) ist erreicht, oder die Anfrage hatte [keinen API-Schlüssel](#anfragen-ohne-api-schlüssel) | Nur die JSON-Variante |
| `500` | **Interner Serverfehler** — meist ein Fehler auf unserer Seite | Einige Male — siehe [Wiederholungen](#wiederholungen) |
| `502` `503` `504` | Gateway- oder Timeout-Fehler | Ja |

## Fehlerformat

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

```json theme={null}
{
  "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](https://help.polygon-one.com/api-reference/introduction.md#duplikatwarnungen) |
| `code` | Optional: ein stabiler Code, z. B. bei Geometrie- und Annahmefehlern der [Parzellen-Endpunkte](https://help.polygon-one.com/api-reference/geo-analysis.md#fehlercodes) oder `EXPORTS_BLOCKED` bei Downloads |

Die einzige Ausnahme: Beim `429` des Rate-Limits ist `error` ein **Objekt**, kein String — siehe
[Rate-Limit](#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](https://help.polygon-one.com/api-reference/batch-import.md#fehlerschlüssel-stabil,-nicht-lokalisiert),
  [Fehlerschlüssel PPWR](https://help.polygon-one.com/api-reference/ppwr.md#fehlerschlüssel),
  [Fehlercodes Parzellen](https://help.polygon-one.com/api-reference/geo-analysis.md#fehlercodes).
* **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:

```json theme={null}
{ "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](https://help.polygon-one.com/api-reference/batch-import.md#teil-akzeptanz-und-idempotenz) |
| PPWR-Stammdaten (`components`, `units`, `formats`, `links`, `article-links`) | Ja — **außer Einheiten-Zeilen ohne `internalRef`**, die jedes Mal eine neue Einheit anlegen. Siehe [PPWR](https://help.polygon-one.com/api-reference/ppwr.md#einheiten:-die-referenz-falle) |
| `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](https://help.polygon-one.com/api-reference/geo-analysis.md#idempotenz) |
| `POST /api/v1/ppwr/documents` | Siehe [Duplikate und Wiederholungen](https://help.polygon-one.com/api-reference/ppwr.md#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](mailto: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](https://help.polygon-one.com/api-reference/geo-analysis.md#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](https://help.polygon-one.com/api-reference/introduction.md#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](https://help.polygon-one.com/api-reference/openapi.json).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.