Fouten, paginering & veilig herhalen

Een antwoord begrijpen

Een lijstantwoord heeft data, revision, total, nextCursor en requestId. Een detailantwoord heeft data, revision en requestId. Bij schrijfacties bevat data de aangemaakte of gewijzigde ID, niet automatisch het volledige dossier. Lees dat zo nodig na.

Fouten uit de API gebruiken error.code en error.message plus requestId. Bij bestandsfouten uit de bestaande opslagroute kan error een tekst zijn met een aparte code. Bewaar requestId of de correlatie-ID voor onderzoek, zonder sleutels en complete klantinhoud te loggen.

Door een lijst bladeren

Gebruik limit tussen 1 en 100; standaard is 50. De eerste cursor is 0. Zolang nextCursor niet null is, haal je de volgende pagina op met die cursor én dezelfde revision. Je blijft daardoor door dezelfde gegevensversie bladeren terwijl het bedrijf verder werkt.

GET /api/v1/projects?limit=50

# Stel: revision = 42 en nextCursor = 50
GET /api/v1/projects?limit=50&cursor=50&revision=42

Zoeken en filteren

De ondersteunde lijstfilters zijn q, status, project, owner en type. q zoekt in naam, titel of nummer; de andere filters vergelijken de opgeslagen waarde exact. Gebruik type bij /records voor een object-ID, of liever de gerichte objectroute. Een onbekend filter geeft een fout.

URL-encode waarden, vooral spaties en veldsleutels met bijzondere tekens. Willekeurige properties-filters, sortering en een algemeen querytaaltje zijn in deze versie niet beschikbaar. Haal voor zo’n selectie de passende lijst op en filter in jouw toepassing.

Revisie voorkomt overschrijven

Iedere dossierwijziging gebruikt If-Match met de revisie die je hebt gelezen. Wijzigt een collega intussen de werkruimte, dan kan jouw schrijfverzoek 409 teruggeven. Ook een wijziging in een ander dossier kan de werkruimterevisie verhogen.

Lees opnieuw, beoordeel of je voorgenomen wijziging nog klopt en maak vervolgens een nieuwe specifieke schrijfopdracht. Gebruik niet steeds blind de nieuwste revisie met dezelfde zakelijke aanname. De API biedt geen force-write.

Idempotentie voorkomt dubbel aanmaken

Gebruik bij dossier- en schemawijzigingen een Idempotency-Key van 8–100 tekens met letters, cijfers, punt, liggend streepje, onderstreping of dubbele punt. Kies een vaste sleutel voor één concrete handeling, bijvoorbeeld intake-847-project-aanmaken.

Bij een netwerk-timeout herhaal je exact methode, pad, body, If-Match en Idempotency-Key. Als de wijziging al was opgeslagen, herkent MANE de ontvangstbevestiging en geeft replayed:true terug. Dezelfde sleutel met andere inhoud, route of revisie geeft een conflict.

Gebruik dus een nieuwe sleutel voor een bewust gewijzigde opdracht na een conflict. Bestandsuploads en webhookbeheer gebruiken een andere route en vragen deze headers niet. Uploads herkennen dezelfde bestandsinhoud, naam en MIME-type.

Veelvoorkomende statuscodes

Ontwerp je herstelroute

Beperk gelijktijdige schrijfacties op dezelfde MANE; serialiseer waar mogelijk. Gebruik een eigen wachtrij met maximale retrylimieten. Bekijk mislukte berichten en laat een mens beslissen bij tegenstrijdige gegevens.

Voor gebeurtenissen gebruik je GET /events?after=<laatste-event-id>&limit=100. Bewaar event-ID’s als strings. Deze cursor is een gebeurtenis-ID, niet de numerieke lijstoffset van /projects. Ga verder tot nextCursor null is.