Felhantering

Servern ska vid varje HTTP anrop returnera en HTTP svarskod.

Om ytterligare information behöver delges konsumenten skall schemat som specificeras i RFC 7807Öppnas i ny flik användas

Om HTTP svarskoderna inte räcker SKALL (FEL.01) API:et beskriva feldetaljer enligt schemat nedan.

Att beskriva feldetaljer (eng: problem details) är baserat på RFC 7807Öppnas i ny flik.

Schema för att beskriva feldetaljer

Schemat enligt RFC 7807 kan innehålla nedan attribut och kräver att mediatypen application/problem+json eller application/problem+xml används i svaret.

Attribut	Beskrivning
type	En URI som identifierar problemtypen som skall vara mer specialiserad än statuskoden. URI:n skall peka på dokumentation av feltypen om den används.
title	En kort beskrivning av problemtypen. Dvs att beskrivningen alltid ska vara identisk för samma typ av fel. Om inte type är angivet skall title reflektera beskrivningen av statuskoden.
status	Detsamma som statuskoden för HTTP-svaret om det används. Kan vara lämpligt att använda om svaret behöver vara självförklarande.
detail	Kort beskrivning av det faktiska felet, avsedd för läsning av människa.
instance	En URI som identifierar den faktiska resursen.

Feldetaljer kan utökas med nya attribut.

Exempel:

curl -X POST "https://gw.api.bolagsverket.se/foretagsinformation/v2/organisationer/1234567-922/kontaktuppgifter" \
    -H  "Accept: */*" -H "Content-Type: application/json" \
    -d '{"email":"lisa.testperson@example.se"}' -i  

HTTP/1.1 400                                                                   
Content-Type: application/problem+json                                              
                    
{                                                                               
  "type" : "https://example.com/probs/req-parameters",                
  "title" : "Felaktiga anropsparametrar",                     
  "status" : 400,
  "detail" : "Felaktigt organisationsnummer",
  "instance" : "/foretagsinformation/v2/organisationer/1234567-922",
  "invalid-parameters" : [ 
    {
      "reason" : "Organisationsnummer ej giltigt",
       "value" : "1234567-922",
       "property" : "organisationsnummer"
     }
   ]
}

Utökning med nya attribut

I exemplet ovan är invalid-parameters en utökning. Konsumenter av ett API skall ignorera utökningar som de inte känner igen.

Notera!
Det är inte möjligt att utöka med nya ”standardattribut” utan att ändra mediatypen med denna design.

Utökning med identifierare för ett specifikt fel

För att underlätta felsökning och få en ökad spårbarhet kan en identifierare för det specifika felet förmedlas till konsumenten. Om det mönstret tillämpas skall identifieraren förmedlas på följande sätt.

HTTP/1.1 400                                                                   
Content-Type: application/problem+json                                              
                                                                                 
{                                                                               
  "type" : "https://example.com/probs/req-parameters",                
   "title" : "Felaktiga anropsparametrar",                     
   "status" : 400,
   "detail" : "Felaktigt organisationsnummer",
   "instance" : "/foretagsinformation/v2/organisationer/1234567-922",
   "invalid-parameters" : [ 
      {
         "reason" : "Organisationsnummer ej giltigt", 
         "value" : "1234567-922",
         "property" : "organisationsnummer",
      }
   ]
   "transaction-id": "86032cbe-a804-4c3b-86ce-ec3041e3effc"
}