Fel
Fel och statuskoder
Alla fel har samma form, oavsett vilken rutt de kommer från. Koden i error är den du bygger logik på; den betyder alltid samma sak och kommer aldrig att byta betydelse.
Felobjektet
{
"error": "period_locked",
"message": "Perioden 2026-03 är momsspärrad och kan inte bokföras i.",
"detail": {
"period": "2026-03"
},
"request_id": "0f9c2f1e-7b3a-4c11-9d55-1a2b3c4d5e6f"
}| Fält | Typ | Alltid | Betydelse |
|---|---|---|---|
error | string | ja | Maskinkod i snake_case. Stabil för alltid — det här är det enda fältet en integration ska grena på. Nya koder kan tillkomma; en befintlig kod byter aldrig betydelse. |
message | string | ja | Förklaring på svenska, riktad till människan som felsöker. Får formuleras om när som helst och är aldrig en del av kontraktet. |
detail | object | nej | Strukturerade uppgifter om just det här felet — aldrig råtext ur databasen. |
request_id | string | ja | Anropets id, också i svarshuvudet X-Request-Id. Ta med det i ett supportärende så går anropet att peka ut i loggen. |
request_id finns också i svarshuvudet X-Request-Id, även på lyckade svar. Logga det på din sida — då går ett enskilt anrop att peka ut i efterhand i stället för att återskapas.
Bygg aldrig logik på message. Den är skriven för människan som felsöker och kan formuleras om när som helst.
Statuskoder
Statusen bär betydelse, och betydelsen är densamma på varje rutt.
| Kod | Vad det gäller | Vad du gör |
|---|---|---|
| 200 | Klart | Anropet gick igenom. Svarets form står vid respektive endpoint. |
| 400 | Formen | Kroppen eller en parameter går inte att läsa. Svaret säger vilket fält det gäller — rätta det och skicka om. |
| 401 | Nyckeln | Saknad, felformad, okänd eller återkallad nyckel. Ett omförsök med samma nyckel ger samma svar. |
| 403 | Behörigheten | Nyckeln är giltig men saknar den behörighet rutten kräver. Skapa en nyckel med rätt behörighet — samma nyckel kommer aldrig att lyckas. |
| 404 | Resursen | Adressen eller posten finns inte i den här installationen. |
| 409 | Idempotenskrock | Samma Idempotency-Key har redan använts för ett anrop med annat innehåll. Välj en ny nyckel. |
| 413 | För stor kropp | Anropet är större än ruttens tak. Taken står i referensen per rutt. |
| 422 | Mottagen, men inte behandlingsbar | Anropet var läsbart och det som skickades in är sparat — det gick bara inte att bokföra. Skälet står i svaret. Skicka inte om det oförändrat; någon ska titta på det. |
| 429 | Takten | Kvoten för timmen är förbrukad. Huvudet Retry-After säger hur många sekunder som återstår. |
| 500 | Vår sida | Något gick fel hos installationen. Ta med request_id i ett supportärende. |
| 502 | Lagringen | Ett dokument kunde inte lagras. Leverera om. |
| 503 | Inte redo | Installationen saknar konfiguration, eller en session kunde inte skapas. Försök igen. |
422 är inte ett fel — det är bokföringen som håller
Ett bokföringsprogram som går att runda via sitt API är inte ett bokföringsprogram. Momslås, oföränderliga verifikat och avslutade räkenskapsår gäller därför lika mycket för ett anrop som för en människa i gränssnittet — de sitter i databasen, inte i knapparna.
Följden är att vissa anrop svarar 422 i stället för att lyda. En order som inte går att kontera rätt sparas med sitt skäl och syns i listan över mottagna ordrar. En faktura som inte kan bokföras i en låst period ligger kvar som utkast. Ingenting kastas: det som tagits emot försvinner aldrig för att nästa steg inte gick, eftersom en spärrad post som försvinner är omöjlig att skilja från en post som aldrig kom.
Omförsök och idempotens
Skrivanrop kräver huvudet Idempotency-Key — 8–255 tecken som du väljer själv, gärna ditt eget ordernummer. Det är obligatoriskt och inte valfritt, av ett skäl som är värt att säga rakt ut: ett nätverk som tappar svaret men inte anropet är det normala felet. Utan huvudet blir varje timeout en risk för dubbel bokföring.
- Samma nyckel, samma kropp — du får det första svaret tillbaka, och huvudet
Idempotent-Replay: true. Ingen andra faktura skapas. - Samma nyckel, annan kropp — 409. Det fångar den vanligaste förväxlingen: ett ordernummer som återanvänds för en annan faktura.
- Ny nyckel — ett nytt anrop.
Sparade svar städas efter 72 timmar. Ett omförsök senare än så räknas som ett nytt anrop.
Vid 429: vänta det antal sekunder Retry-After anger. Vid 5xx: försök igen med samma Idempotency-Key — det är precis det den är till för. Vid 4xx utom 429: ett omförsök ger samma svar. Rätta anropet i stället.
Alla felkoder
Uppräkningen kommer ur samma datafil som referenssidorna, så den är fullständig.
| error | Betydelse | Förekommer på |
|---|---|---|
db_error | Underlaget kunde inte läsas. | /api/stats/overview/api/stats/monthly/api/stats/byra |
idempotency_conflict | Samma Idempotency-Key har redan använts med en annan kropp. | /api/v1/verifikat/api/v1/kundfakturor |
idempotency_in_progress | Ett anrop med samma Idempotency-Key behandlas just nu. Skicka om exakt samma anrop om en stund — du får då det första svaret. Byt INTE nyckel: det första anropet kan mycket väl ha bokfört. | /api/v1/verifikat/api/v1/kundfakturor |
idempotency_required | Huvudet Idempotency-Key saknas. | /api/v1/verifikat/api/v1/kundfakturor |
insufficient_scope | Nyckeln är giltig men saknar behörigheten rutten kräver. | de flesta rutter |
invalid_request | En parameter går inte att läsa — svaret säger vilken. | /api/v1/verifikat/api/v1/kundfakturor |
key_revoked | Nyckeln är återkallad av installationens ägare. | de flesta rutter |
method_not_allowed | Endast POST. En token är inte en resurs som kan hämtas om. | /api/byra/token |
no_access | Token duger men öppnar ingenting — åtkomsten kan vara återkallad. | /api/stats/byra |
payload_too_large | Kroppen är större än 512 kB. Ett verifikat är några kilobyte; taket stoppar en kropp som inte är ett. | /api/v1/verifikat/api/v1/kundfakturor |
period_locked | Perioden är låst, momslåst eller räkenskapsåret avslutat. Verifikatet är läst men kan inte bokföras — svaret säger vilken spärr som gäller. | /api/v1/verifikat |
rate_limited | Nyckelns kvot för timmen är förbrukad. Retry-After säger när den återställs. | de flesta rutter |
server_misconfigured | Installationen saknar konfiguration för API:et. | de flesta rutter |
token_unavailable | Nyckeln är giltig men sessionen kunde inte skapas. | /api/byra/token |
unauthorized | Saknad, felformad eller okänd nyckel. | de flesta rutter |
unprocessable | Motorn tog emot verifikatet men kunde inte bokföra det: ett konto som saknas eller är avaktiverat, en verifikationsserie som inte finns för året, ett datum utan räkenskapsår, eller en dimension som inte är aktiv. | /api/v1/verifikat/api/v1/kundfakturor |
Nya koder kan tillkomma — se Ändringar. En befintlig kod byter aldrig betydelse, så en integration som hanterar en okänd kod som ett allmänt fel fortsätter fungera.