Guide

Feil og feilsøking

Alle feil er maskinlesbare. Forretnings-API-et svarer med RFC 9457-feildokumenter; token-endepunktet svarer med OAuth 2.0-feil-JSON. Denne siden er hele feilflaten — kroppen, svarene alle endepunkter deler, og hva du gjør med hvert av dem.

Feildokumentet

Alt som ikke er 2xx fra forretnings-API-et kommer med Content-Type: application/problem+json og et RFC 9457-feildokument. De fem RFC 9457-medlemmene er alltid med, og plattformen legger til tre egne:

Feildokument

{
  "timestamp": "2026-08-21T11:58:21.123Z",
  "status": 422,
  "type": "urn:visena:validation:illegal-argument",
  "errorType": "ILLEGAL_ARGUMENT",
  "title": "Unprocessable Entity",
  "detail": "companyId 'bQ4wR8' does not resolve to an existing company",
  "instance": "/acme/api/v1/en/person"
}

Medlem	Type	Hva det er
`timestamp`	string (date-time)	Når plattformen laget feilen. Logg den — det er slik vi finner kallet hos oss.
`status`	integer	HTTP-statusen, gjentatt inne i kroppen.
`type`	string (URI)	Feiltypen: en stabil URN som `urn:visena:validation:illegal-argument` eller `urn:visena:data:instance-not-found`, og `about:blank` der det ikke finnes noe mer presist å si enn statusen. Dette er medlemmet du forgrener på.
`errorType`	string	Samme klassifisering under plattformens eget navn, `ILLEGAL_ARGUMENT` for URN-en over. Oppgir du én av dem, er tilfellet entydig identifisert.
`title`	string	HTTP-statusens engelske reason phrase — `Unprocessable Entity`. En protokollstreng, ikke en melding til brukerne dine.
`detail`	string	Forklaringen skrevet for mennesker. Den oversettes ut fra `{locale}`-segmentet i URL-en, og ved en valideringsfeil navngir den feltet som er feil.
`instance`	string	Stien til kallet som feilet.
`additionalData`	object	Strukturerte tillegg, på de feilene som har noen. Er det ingen, er medlemmet helt borte fra kroppen — ikke `null`.

Forgren på status og type; vis detail til mennesker, og logg den, men aldri parse den. Den er prosa, og den oversettes.

⚠

instance er ikke Visena-instansen. I et RFC 9457-dokument betyr instance kallet som feilet, så medlemmet inneholder en sti: /acme/api/v1/en/person. Instansnavnet er første segment i den stien — acme.

Token-endepunktet er annerledes

Å hente et access token er en OAuth 2.0-utveksling med client_credentials, og den feiler på OAuth 2.0-måten framfor med et feildokument: en JSON-kropp med en error-kode — invalid_client, invalid_grant, invalid_scope — og normalt en error_description ved siden av. Legitimasjon, scopes og selve utvekslingen står på Legitimasjon og tokener.

Delte feil — alle endepunkter

Referansesidene lister bare svarene som er spesifikke for det enkelte endepunktet. I tillegg til dem kan alle endepunkter svare med disse fire:

Status	Betydning
401	Token mangler, er utløpt eller er trukket tilbake. Hent et nytt token og prøv én gang på nytt.
403	Tokenet mangler scopet denne metoden krever — lese-scopet for trygge metoder, skrive-scopet for endringer — eller det er hentet for en annen instans.
404	Ukjent instansnavn i URL-en.
500	Uventet serverfeil. Prøv på nytt med eksponentiell backoff, og oppgi `timestamp` fra feilkroppen hvis den vedvarer.

Instansnavnet er første stisegment i hver forretnings-URL — /{instanceName}/api/v1/{locale}/person — så en skrivefeil der svarer 404 på alle endepunkter samtidig, ikke bare på det du tilfeldigvis kalte.

Et endepunkt kan gi samme kode en trangere betydning. En 403 kan også si at funksjonen bak nettopp det endepunktet ikke er slått på for instansen, og de fleste 404-ene handler om id-en i stien framfor om instansnavnet. Les type og detail før du konkluderer med at tokenet er feil: for kodene et endepunkt dokumenterer selv, er dets egen svartabell i referansen autoriteten.

Statuskoder, og hva du gjør med dem

Status	Betydning	Hva du gjør
400	Ugyldig kall — ødelagt JSON, validering som feilet, en parameterverdi endepunktet ikke godtar.	Rett kallet; `detail` navngir problemet. Ikke send det uendret på nytt.
401	Token mangler, er utløpt eller er trukket tilbake.	Hent et nytt token og prøv én gang på nytt. Gjentatte 401-er er et legitimasjonsproblem, ikke et tidsproblem.
403	Tokenet mangler scopet metoden krever, er hentet for en annen instans, eller funksjonen bak endepunktet er ikke slått på her.	Sammenlign tokenets scope med metoden, sjekk instans-segmentet, og hent et nytt token med de scopene du faktisk trenger.
404	Ukjent instansnavn, eller en id som ikke finnes — eller ikke er din å se.	Kontroller instans-segmentet, deretter id-en. I en synk behandler du 404 på en id du kjenner som «borte».
409	Konflikt — et organisasjonsnummer som alt er i bruk, en flytting som kolliderer med det som ligger der, eller en sletting som ville kaskadert lenger enn du ba om.	Les `detail`. Sjekk for duplikater først, eller send på nytt med den bekreftelsen endepunktet tilbyr, for eksempel `acknowledgeCascade`.
415	Feil `Content-Type` — nesten alltid en `PATCH` sendt uten `application/merge-patch+json`.	Sett den content-typen endepunktet dokumenterer.
422	Et velformet kall som peker på noe uoppløselig — en referert id som ikke finnes.	Rett referansen. Ingenting ble skrevet.
500	Uventet serverfeil.	Prøv på nytt med eksponentiell backoff. Vedvarer den, send oss `timestamp` og kroppen.

En fornuftig retry-policy

Klassifiser før du prøver på nytt. Nettverksfeil og 5xx er forbigående. 400, 403, 409, 415 og 422 er det ikke — samme kall gir samme svar.
Hent nytt token én gang på 401. Ett nytt token, ett nytt forsøk. En ny 401 på et helt ferskt token er et legitimasjons- eller scope-problem, og det trenger et menneske framfor et nytt forsøk.
Trekk deg eksponentielt tilbake, med jitter. 1s → 2s → 4s → 8s er en god trapp, og jitteren er det som hindrer at en flåte av arbeidere prøver på nytt i takt.
Logg hele feildokumentet. timestamp, type og detail, sammen med metoden og stien i kallet. Det er forskjellen på en henvendelse vi sporer på sekunder og en som må reproduseres.
Sett et tak på forsøkene, og løft så feilen fram. Når trappen er brukt opp, stopper du og løfter feilen dit et menneske ser den. En jobb som prøver i det uendelige ser sunn ut mens den ikke får gjort noe.

En retry-løkke kan bli verre enn feilen den skjuler. Å sende en 4xx uendret på nytt kan ikke lykkes, og å svare hver 401 med et nytt token-kall gjør én utløpt legitimasjon til et lastproblem for alle andre integrasjoner på instansen. Prøv bare på nytt der det kan lykkes, bare med backoff, og hent aldri et token per kall.

Rask feilsøkingstabell

Symptom	Vanlig årsak
Alle kall gir 401	Tokenet er utløpt og hurtiglageret ditt fornyer det ikke, eller legitimasjonen ble trukket tilbake i en rotasjon.
Lesing virker, skriving gir 403	Tokenet er hentet med lese-scopet alene.
Alt gir 403 på én instans	Tokenet er hentet for en annen instans enn den som står i stien.
Alle endepunkter gir 404, også de som virket i går	Instans-segmentet er feil — en skrivefeil, eller et navn tatt med fra et annet miljø.
Token-kallet gir 400 `invalid_scope`	Ingen `scope`-parameter, eller et scope legitimasjonen ikke har. Plattformen velger aldri en standard for deg.
`PATCH` gir 415	`Content-Type` er ikke `application/merge-patch+json`.
Oppretting av company gir 409	Et selskap med det organisasjonsnummeret finnes alt — sjekk `/company/duplicates` og oppdater i stedet.

Trenger du oss likevel, send metoden og stien til kallet som feilet, feildokumentet — timestamp, type, detail — og din clientId. Aldri hemmeligheten. Det er alt vi trenger for å finne kallet. Send det til sales@visena.com.