# Fouten & opnieuw proberen

Deze pagina beschrijft fouten bij aanvragen met een API-key. Kijk bij een fout eerst naar de HTTP-status en daarna naar `error.code`. Bewaar de `request_id` voor onderzoek, samen met tijdstip en endpoint. Deel geen wachtwoorden, tokens of pakketpayloads als dat niet nodig is.

## De belangrijkste statuscodes

| Status | Betekenis | Wat je doet |
| --- | --- | --- |
| `200` / `201` | Gelukt / aangemaakt. | Verwerk `data` en bewaar ontvangen object-ID’s voor vervolgaanvragen. |
| `400` | Ongeldige JSON, onbekend veld, verkeerde filter of ontbrekende header. | Corrigeer het verzoek. |
| `401` | De API-key ontbreekt, is ongeldig, verlopen of ingetrokken, of je organisatie heeft geen toegang. | Controleer de header en de keystatus in de console; vervang een verlopen of ingetrokken key. |
| `403` | De key heeft onvoldoende rechten voor deze aanvraag. | Controleer de vereiste scope en maak zo nodig in de console een key met de juiste rechten. |
| `404` | Route of object niet gevonden binnen je toegang. | Controleer ID, organisatie en URL. |
| `409` | Conflict, bijvoorbeeld dezelfde idempotentiesleutel met een andere body. | Onderzoek het conflict vóór opnieuw proberen. |
| `412` | Een ontbrekende of verouderde `If-Match`-versie. | Lees de nieuwste levering en beoordeel de wijziging opnieuw. |
| `422` | Inhoudelijk ongeldige velden of combinatie. | Pas de invoer aan volgens het contract. |
| `429` | Tijdelijke aanvraaglimiet. | Wacht volgens `Retry-After`; verminder je aanvraagtempo. |
| `500` / `503` | Interne fout of tijdelijk onbeschikbare dienst. | Bewaar request-ID en probeer later gecontroleerd opnieuw. |

Een te grote of onleesbare body kan als `400` worden afgewezen; de idempotente verwerkingsroutes kunnen voor een te grote body `413` teruggeven. De huidige bovengrens is 2 MiB.

## Limieten

API-keys hebben een limiet van **600 aanvragen per minuut per key**.

De server geeft bij limieten `Retry-After: 60`. Voeg bij herhaalde tijdelijke fouten wachttijd toe en stop als dezelfde fout blijft optreden. Maak geen nieuwe keys om een limiet te omzeilen.

## Dubbele verwerking voorkomen

Bij `POST /deliveries/v1/parcels`, `POST .../events` en `POST .../attempts` is `Idempotency-Key` verplicht. Kies voor elke nieuwe actie een unieke sleutel van 8–128 tekens.

Bij een timeout herhaal je dezelfde methode, URL, sleutel en **exact dezelfde bodybytes**. Bewaar daarom de oorspronkelijke JSON; opnieuw serialiseren met een andere sleutelvolgorde kan een conflict geven. Een herhaling retourneert het opgeslagen resultaat met `Idempotency-Replayed: true` en nul extra eenheden.

Gebruik je dezelfde sleutel voor een andere inhoud, dan volgt `409 idempotency_conflict`. De idempotentierecords verlopen in deze pilot nog niet automatisch.

## Een gelijktijdige update afhandelen

Lees de levering met `GET /deliveries/v1/parcels/{id}`. Bewaar de responseheader `ETag`, bijvoorbeeld `"3"`. Stuur deze bij een wijziging mee:

```http
PATCH /deliveries/v1/parcels/<entry_id>
Authorization: Bearer <api-key>
Content-Type: application/json
If-Match: "3"

{"parcel_weight": 1200}
```

Bij `412` heeft iemand of een achtergrondproces de versie inmiddels gewijzigd. Lees opnieuw, vergelijk de gewijzigde gegevens en bepaal of je update nog klopt. Verstuur niet blind dezelfde wijziging onder een nieuwe versie.

## Veilig opnieuw proberen

GET-verzoeken kun je na een tijdelijke netwerkfout opnieuw doen. Voor de drie genoemde POST-routes gebruik je de bestaande idempotentiesleutel. Probeer een `401` of `403` pas opnieuw nadat je de key of rechten hebt gecontroleerd; herhaald versturen lost een toegangsprobleem niet op.

## Producttoegang niet actief

`403 product_not_active` betekent dat de organisatie nog geen toegang heeft tot de gevraagde productfunctie. Nieuwe conceptaccounts ondersteunen alleen portal, keybeheer en gebruiksinzage. Een andere scope of een nieuwe key verandert dit niet. Er wordt geen betaald gebruik automatisch geactiveerd.