Fouten en limieten

#Foutantwoord

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "This key requires companies:write.",
    "requestId": "40643344-b675-4de8-bc77-a0531bd17461"
  }
}

Bewaar de requestId voor onderzoek of een supportvraag. Elk API-antwoord bevat ook een X-Request-Id-header. Alle geauthenticeerde antwoorden hebben Cache-Control: no-store. Foutcodes zijn bedoeld voor code; gebruik de tekst als toelichting.

HTTP	Code	Actie
400	`VALIDATION_ERROR`	Controleer JSON, veldnamen, typen, enumwaarden en vereiste velden
401	`UNAUTHORIZED`	Controleer sleutel, vervaldatum, lidmaatschap en API-beschikbaarheid
403	`INSUFFICIENT_SCOPE`	Vink het vereiste sleutelrecht aan
403	`FORBIDDEN`	Controleer actuele rolrechten, functies en abonnementsquota
403	`READ_ONLY`	De workspace staat wijzigingen momenteel niet toe
404	`NOT_FOUND`	Controleer pad en UUID; een record uit een andere workspace geeft dezelfde fout
405	`METHOD_NOT_ALLOWED`	Gebruik een ondersteunde methode; de `Allow`-header toont welke
409	`CONFLICT` of `RESOURCE_ARCHIVED`	Lees de actuele toestand en pas het verzoek aan
413	`PAYLOAD_TOO_LARGE`	Verklein de JSON-body tot maximaal 64 KiB
415	`UNSUPPORTED_MEDIA_TYPE`	Gebruik `Content-Type: application/json` voor een JSON-body
429	`RATE_LIMITED`	Wacht het aantal seconden uit `Retry-After`
500	`INTERNAL_ERROR`	Tijdelijke of interne fout; gebruik de request-ID bij support

#Verzoeklimiet

Iedere API-sleutel mag maximaal 120 verzoeken per minuut doen. De limiet geldt over alle endpoints samen en wordt in de database bijgehouden, ook bij meerdere applicatieprocessen. Het venster begint bij het eerste verzoek en wordt na een minuut opnieuw gestart.

X-RateLimit-Limit geeft 120; X-RateLimit-Remaining geeft het resterende aantal. Een overschrijding geeft 429 met Retry-After in hele seconden. Beperk gelijktijdigheid en wacht bij retries steeds iets langer. Het maandelijkse API-quotum van het abonnement geldt daarnaast; een uitgeput quotum kan 403 geven.

#Invoer en paginering

Stuur geldige JSON met camelCase-velden. Onbekende velden en dubbele queryparameters worden geweigerd. Record-ID's zijn UUID's. limit is een positief geheel getal; de maximale waarde is 200, tenzij het endpoint geen paginering ondersteunt. Booleans in queryparameters zijn letterlijk true of false. Kopieer de ondoorzichtige nextCursor zonder hem te wijzigen.

Voor gedeeltelijke updates stuur je alleen de velden die je wilt veranderen. De API ondersteunt niet algemeen null om velden te wissen: gebruik alleen de typen die in de referentie staan. Een PATCH zonder wijzigingsvelden geeft een validatiefout.

#Veilige retries

GET-verzoeken kun je na een tijdelijke fout herhalen. Gebruik voor retries een vertraging en respecteer Retry-After. Schrijfverzoeken ondersteunen geen idempotency-key. Een verbroken verbinding kan ontstaan nadat een aanmaak al is opgeslagen; een blinde herhaling kan dan een dubbel record veroorzaken. Controleer eerst de lijst of bewaar het ontvangen record-ID.

Voor webhooks geldt een eigen aflevermechanisme met maximaal vijf automatische pogingen. Zie webhooks voor ondertekening, deduplicatie en opnieuw afleveren.