Feilhåndtering

Alle feil fra Spire har samme form, uansett produkt og endepunkt. Målet er at du skal kunne skrive feilhåndteringen én gang.

Formatet

{
  "feil": {
    "kode": "ugyldig_parameter",
    "melding": "forfall må være minst 14 dager frem i tid for forbrukere.",
    "felt": "forfall",
    "dok": "https://spireapi.com/api/feil/#ugyldig_parameter",
    "request_id": "req_01JBX9W2K4"
  }
}

Ved valideringsfeil med flere felt kommer de i detaljer:

{
  "feil": {
    "kode": "ugyldig_parameter",
    "melding": "To felt har feil.",
    "detaljer": [
      { "felt": "forfall", "melding": "Må være en dato." },
      { "felt": "linjer[0].pris", "melding": "Må være et tall." }
    ],
    "request_id": "req_01JBX9W2K4"
  }
}

Tre typer feil

Din feil (4xx). Forespørselen er ugyldig, nøkkelen mangler rettigheter, objektet finnes ikke. Ikke gjenforsøk uten å endre noe. Logg request_id og felt, og vis en forståelig melding til brukeren om det er relevant.

Vår feil (500). Noe gikk galt hos oss. Kallet er ikke registrert, og det teller ikke mot kvoten. Gjenforsøk med samme Idempotency-Key. Vedvarer det, se status og kontakt oss med request_id.

Midlertidig (429, 503). Du har truffet hastighetsgrensen, eller en ekstern kilde er nede og vi har ikke cache. Vent så lenge Retry-After sier, og prøv igjen.

SDK-ene gjør gjenforsøk automatisk for 429, 500, 502, 503 og nettverksfeil. Du trenger bare håndtere 4xx.

Eksempel på robust håndtering

import Spire, { SpireError } from '@spire/sdk';

try {
  const f = await spire.fakturaer.opprett(params, { idempotencyKey: ordre.id });
  await spire.fakturaer.send(f.id);
} catch (e) {
  if (e instanceof SpireError) {
    switch (e.kode) {
      case 'ugyldig_parameter':
        return visFeltfeil(e.felt, e.melding);        // la brukeren rette
      case 'ikke_funnet':
        return visMelding('Mottakeren finnes ikke lenger i registeret.');
      case 'konflikt':
        return hentEksisterende(ordre.id);             // allerede opprettet
      case 'kvote_brukt':
        return varsleAdmin('Spire-kvoten er brukt opp');
      default:
        logg.error('Spire-feil', { kode: e.kode, requestId: e.requestId });
        throw e;
    }
  }
  throw e;
}

Delvise feil

Noen kall kan lykkes delvis. Masseoppslag returnerer én linje per organisasjonsnummer, og hver linje kan være et objekt eller en feil. Batch-sending av meldinger godtar hele batchen (202) og rapporterer feil per mottaker som webhooks. I begge tilfeller er HTTP-statusen for kallet 2xx; feilene ligger i innholdet.

Hva vi lover om feilkoder

• Eksisterende koder fjernes aldri innenfor en API-versjon.
• Nye koder kan legges til. Ha alltid en default-gren.
• melding kan endre ordlyd. Ikke sammenlign tekst.
• HTTP-status for en kode endres aldri.

Alle koder står i referansen.