# Fouten en limieten

Statuscodes, verzoeklimieten, retries en veilige foutafhandeling voor integraties.

## Foutantwoord

```json
{
  "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](/developers/api-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](/developers/webhooks/) voor ondertekening, deduplicatie en opnieuw afleveren.