Agreli
Probeer gratis
Docs / Fouten en limieten

Fouten en limieten

Elke fout heeft dezelfde vorm, een HTTP-status, een vast type en een stabiele code. De melding is Nederlands en bedoeld voor mensen; je programma kijkt naar type en code.

MarkdownOpenAPI

De foutvorm

422 Unprocessable Entity
{
  "error": {
    "type": "invalid_request",
    "code": "template_invalid",
    "message": "Onbekende template_id; zie GET /v1/organization voor de beschikbare templates",
    "request_id": "req_…"
  }
}

request_id staat ook in de kop X-Request-Id. Noem het als je contact opneemt over een verzoek.

Fouttypes

TypeHTTPBetekenis
invalid_request400, 413, 415, 422Ongeldige JSON, verkeerde Content-Type, te groot verzoek of een veld dat niet klopt. code zegt welk.
authentication_error401Geen, ongeldige of verlopen API-sleutel.
permission_error403De sleutel mist het recht, of de werkgever heeft de partner niet (meer) toegelaten.
not_found404Bestaat niet, of is niet zichtbaar voor deze sleutel.
conflict409Kan niet in deze toestand, bijvoorbeeld een onboarding die al is afgerond.
rate_limited429Te veel verzoeken. Wacht het aantal seconden uit Retry-After.
api_error500Fout aan onze kant. Opnieuw proberen met dezelfde Idempotency-Key is veilig.

Veelvoorkomende codes

CodeHTTPWanneer
unauthorized401Geen, ongeldige of verlopen sleutel, of de eigenaar van de sleutel heeft geen toegang meer.
forbidden403De sleutel mist het recht, de werkgever laat de partner niet toe, of de sleutel hoort bij een andere organisatie.
organization_required422Een partnersleutel zonder de kop Agreli-Organization.
organization_invalid422De kop Agreli-Organization is geen geldig org_…-id.
idempotency_conflict422Dezelfde Idempotency-Key met een andere inhoud.
idempotency_in_progress409Een verzoek met dezelfde Idempotency-Key wordt nog verwerkt. Probeer het zo opnieuw.
api_version_invalid422Een onbekende versie in de kop Agreli-Version.
subscription_required403De proef van de werkgever is afgelopen zonder abonnement, of het abonnement is opgezegd. Lopende onboardings gaan door; nieuwe niet.
api_approvals_disabled403Goedkeuren of de ID-controle via de API staat uit bij deze werkgever.
template_invalid422Onbekende of niet goedgekeurde template_id.
location_invalid422Onbekende location_id.
terms_invalid422hours_per_week of hourly_wage_cents ontbreekt of klopt niet.
return_url_invalid422De return_url is geen https-adres.
return_url_not_allowed422Het domein van de return_url staat niet bij de toegestane domeinen.
metadata_invalid422Metadata is geen plat object, of een sleutel of waarde voldoet niet.
metadata_personal_data422Een waarde in metadata lijkt op een persoonsgegeven.
field_not_updatable422PATCH met een ander veld dan reference of metadata.
data_version_required422Goedkeuren zonder de gecontroleerde data_version.
limit_invalid, cursor_invalid422Ongeldige limit of starting_after bij het bladeren.
events_invalid, url_insecure, url_not_public422Een webhookadres met een onbekende gebeurtenis, zonder https of naar een intern adres.
overlap_invalid422overlap_hours bij het vernieuwen van een webhookgeheim is geen getal van 0 tot 168.
webhook_disabled, delivery_pending422Opnieuw versturen naar een uitgeschakeld adres, of een aflevering die al klaarstaat.
since_invalid, type_invalid422GET /v1/events met een ongeldig tijdstip of een onbekende gebeurtenis.
nothing_to_advance, payroll_busy409Sandbox: er valt niets na te spelen, of de salarisverwerking loopt al.
invalid_json, content_type, too_large400, 415, 413Geen geldige JSON, geen Content-Type: application/json, of meer dan 100 kB.
rate_limited429Te veel verzoeken.
internal500Fout aan onze kant.

Deze lijst is niet volledig: elke controle in de backend heeft een eigen code. Behandel een onbekende code op basis van het type.

Snelheidslimiet

Per sleutel gelden 120 verzoeken per minuut. Elk antwoord vertelt hoe je ervoor staat:

KopBetekenis
RateLimit-LimitHet aantal verzoeken per minuut (120).
RateLimit-RemainingWat er deze minuut nog over is.
RateLimit-ResetSeconden tot de teller opnieuw begint.
Retry-AfterAlleen bij 429: wacht zoveel seconden.

Opnieuw proberen

  • Bij 429: wacht het aantal seconden uit Retry-After.
  • Bij 500, een time-out of een verbroken verbinding: probeer opnieuw met dezelfde Idempotency-Key. Dan wordt niets dubbel aangemaakt.
  • Bij andere 4xx: niet blind herhalen. Pas het verzoek aan op basis van code.

Bladeren

Lijsten (GET /v1/onboardings, GET /v1/employees, GET /v1/webhooks/{id}/deliveries, GET /v1/events) geven { "object": "list", "data": [...], "has_more": true, "next_cursor": "onb_…" }. Vraag de volgende pagina op met starting_after=<next_cursor>. limit is 1 tot 100, standaard 25 (50 bij events). De nieuwste staan bovenaan, behalve bij GET /v1/events: daar de oudste.

Terminal
curl "https://app.agreli.nl/api/public/v1/onboardings?status=in_review&limit=50&starting_after=onb_…" \
  -H "Authorization: Bearer $AGRELI_API_KEY"