API-felkoder och svar

Alla endpoints följer samma mönster och varje felsvar innehåller ett beskrivande meddelande i antingen JSON- eller XML-format, beroende på anropet. Nedan beskrivs vanliga felkoder och hur de ska tolkas.

Lyckade svarskoder

200 OK — Anropet lyckades och data returnerades enligt förväntan.

204 No Content — Anropet lyckades, men det finns inget innehåll att returnera (till exempel vid sökning som inte ger några träffar).

Klientfel (4xx)

Dessa indikerar problem med anropet från din applikation och innebär vanligtvis att parametrar, autentisering eller resursidentifierare är felaktiga.

400 Invalid Request — Anropet kunde inte behandlas på grund av ogiltiga parametrar eller felaktig syntax. Kontrollera payload och struktur i anropet.

401 Unauthorized — API-nyckeln saknas eller är ogiltig. Alla anrop kräver en giltig nyckel i Authorization-headern.

403 Forbidden — Den API-nyckel som används saknar behörighet för den begärda operationen. Kontrollera rättigheter, roller eller partnerbehörigheter.

404 Not Found — Den begärda resursen (till exempel endpoint, konto eller identifierare) finns inte. Orsakas ofta av felaktig URL eller ogiltig parameter.

409 Conflict — En konflikt har uppstått, vanligtvis på grund av att en resurs redan existerar eller att tillståndet är inkonsekvent, till exempel vid försök att skapa en redan existerande unik identifierare.

422 Unprocessable Entity — Data är syntaktiskt korrekt men semantiskt ogiltigt. Det innebär oftast att obligatoriska fält saknas eller att värden inte uppfyller schema- eller Peppol-valideringsregler.

429 Too Many Requests — Du har nått en gräns för antal anrop. Minska anropsfrekvensen eller implementera omförsök med fördröjning (exponential backoff).

Serverfel (5xx)

Dessa indikerar ett problem på Qvalias sida. I de flesta fall bör du försöka igen och, om felet kvarstår, kontakta Qvalias support.

500 Internal Error — Servern stötte på ett oväntat fel. Detta beror inte på klientanropet. Kontakta support om problemet kvarstår.

Tolka felsvar

Utöver HTTP-statuskoden returnerar Qvalia ett beskrivande felmeddelande i svaret. Om du begär XML returneras svaret i XML-format, annars i JSON (standard).

Rekommendationer

• Kontrollera alltid HTTP-statuskoden först. Vid 4xx-fel ska anropet korrigeras; vid 5xx-fel kan ett nytt försök efter kort fördröjning vara lämpligt.

• Implementera tydlig felhantering och loggning i din integration så att både statuskod och felmeddelande sparas.

• Vid autentiseringsfel, verifiera att API-nyckeln finns med, är korrekt och har rätt behörigheter.

• Hantera rate limiting (429) genom att implementera omförsök med fördröjning.

• Använd transaktionsloggen i Qvalia-portalen för att koppla API-fel till behandlade meddelanden och metadata vid operativ felsökning.