Foutcodes en limieten

Doel

Een overzicht van alle fout- en statuscodes van de Leads-API (POST/PATCH /api/v1/leads), zodat je integratie fouten kan herkennen en er goed op kan reageren.

Antwoordvorm

Elk foutantwoord heeft dezelfde vorm:

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "fields": {
      "email": "invalid_email"
    }
  }
}

fields staat er alleen bij een validatiefout (code: "validation_error", HTTP 422) en is dan een object: veldnaam → een vaste, machineleesbare code (zoals invalid_email, too_long, name_required, unexpected_field). Die codes zijn een contract en veranderen niet zomaar.

Voorbeeld 6 — omgaan met een 422-validatiefout

curl -i -X POST https://app.plenno.nl/api/v1/leads \
  -H "Authorization: Bearer pln_live_xxxxxxxx_VERVANG_DOOR_JE_EIGEN_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jan Jansen", "email": "niet-een-e-mailadres" }'

HTTP/1.1 422 Unprocessable Entity

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "fields": { "email": "invalid_email" }
  }
}

Behandel dit als een fout in je eigen verzoek: los per veld in error.fields het probleem op en verstuur opnieuw met dezelfde external_id. Blijven proberen zonder aanpassing helpt hier niet.

Alle codes

HTTP	code	Wat is er aan de hand	Wat doe je
400	invalid_json	De body is geen geldige JSON.	Controleer je serialisatie.
400	invalid_payload	De body is geen JSON-object.	Stuur een JSON-object, geen array/string/getal.
400	tenant_selection_not_allowed	Je stuurt organization_id, tenant_id, organizationId of owner_user_id mee.	Haal dat veld weg; de sleutel bepaalt het bedrijf.
401	unauthorized	Sleutel ontbreekt, is onjuist of is ingetrokken.	Controleer de Authorization-header.
404	not_found	(Alleen PATCH) Onbekend ID, niet aangemaakt door deze sleutel, of een mode-mismatch (live/test).	Controleer het lead_id en de gebruikte sleutel.
405	method_not_allowed	Andere methode dan POST (of, op /leads/{id}, dan PATCH).	Gebruik de juiste methode.
409	duplicate_in_progress	Dezelfde external_id wordt op dit moment al verwerkt.	Probeer het over een paar seconden opnieuw.
410	lead_deleted	Deze external_id is eerder verwerkt, maar de aanvraag is daarna in Plenno verwijderd.	Niet opnieuw sturen. Een nieuwe aanvraag vraagt om een nieuwe external_id.
413	payload_too_large	De body is groter dan 16 kB.	Kort message of metadata in.
415	unsupported_media_type	Verkeerde Content-Type.	Stuur application/json.
422	validation_error	Een veld ontbreekt, is te lang, ongeldig of onbekend.	Zie error.fields.
429	rate_limited	Te veel aanvragen.	Wacht Retry-After seconden en probeer opnieuw.
500	internal_error	Er ging iets mis aan onze kant.	Probeer het opnieuw; blijft het fout, meld het bij Plenno.
503	service_unavailable	Plenno kan het verzoek tijdelijk niet verwerken.	Probeer het later opnieuw.

Limieten

• 60 aanvragen per minuut per API-sleutel.
• 120 aanvragen per minuut per IP-adres.

Dezelfde limieten gelden voor POST en PATCH samen. Een normaal websiteformulier komt hier nooit in de buurt.

Voorbeeld 7 — omgaan met 429 en Retry-After

curl -i -X POST https://app.plenno.nl/api/v1/leads \
  -H "Authorization: Bearer pln_live_xxxxxxxx_VERVANG_DOOR_JE_EIGEN_SLEUTEL" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Jan Jansen", "email": "jan@voorbeeld.nl" }'

HTTP/1.1 429 Too Many Requests
Retry-After: 12

{
  "success": false,
  "error": { "code": "rate_limited", "message": "Too many requests for this API key." }
}

Retry-After staat in hele seconden. Wacht minimaal zo lang voordat je het opnieuw probeert, met dezelfde external_id — zo levert de retry nooit een duplicaat op.

Aanbevolen werkwijze

1. Behandel 429 en 5xx (500, 503) als "later opnieuw proberen", met dezelfde external_id.
2. Behandel 4xx (met uitzondering van 429) als een fout in je eigen verzoek: opnieuw sturen zonder aanpassing helpt niet.
3. 410 is definitief — blijf die external_id niet opnieuw aanbieden; gebruik een nieuwe.

Vervolg

Lees Webhooks instellen en beveiligen voor het ontvangen van statuswijzigingen.