Fouten & opnieuw proberen
Begrijp HTTP-statussen, limieten, idempotentie en versieconflicten.
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:
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.