Dela via

Felkoder och felhantering | Graph API-begrepp

  • Artikel

Gäller för: Graph API | Azure Active Directory (AD)

Klientprogram som använder Azure Active Directory (AD) Graph API ska implementera felhantering logik för att agera som smidigt som möjligt olika villkor och ge bästa möjliga upplevelse till sina kunder. I avsnittet beskrivs typerna av fel som Azure AD Graph API returnerar och innehåller allmänna råd om hur du hanterar dem.

Viktigt

Vi rekommenderar starkt att du använder Microsoft Graph i stället för Azure AD Graph API för att komma åt resurser i Azure Active Directory. Vårt utvecklingsarbete är nu samlade på Microsoft Graph och inga fler förbättringar som planeras att Azure AD Graph API. Det finns ett begränsat antal scenarier som Azure AD Graph API kan fortfarande vara lämplig. Mer information finns i Microsoft Graph eller Azure AD Graph blogginlägget i Office Dev Center.

Hantera Graph API-fel

Typer av fel

Graph API-fel uppstår i följande kategorier.

  • Klientfel. Klientfel representeras av 400-serien HTTP-statuskoder. De inkluderar objekt med ogiltiga värden, objekt som saknas obligatoriska egenskaper och egenskapsvärden, försöker komma åt en obefintlig resurs, försök att uppdatera en skrivskyddad egenskap och utelämna autentiseringstoken som krävs. För att lösa dessa fel, åtgärda det underliggande problemet innan du försöker begäran.
  • Fel. Serverfel representeras av 500-serien http-statuskoder som ett tillfälligt directory-fel. De flesta av dessa fel är tillfälliga och kan lösas genom försök.
  • / Nätverksprotokoll fel. Ett flertal nätverksrelaterade fel kan inträffa när de skickar en begäran eller ta emot ett svar, till exempel fel på värddatorn name resolution, tidigt stängd anslutningar och SSL-förhandling-fel. De flesta av dessa fel kan inte matchas av du försöker; det underliggande problemet måste åtgärdas. Dock kan vissa fel, till exempel värden namnmatchning fel eller avbrott, matchas av försök.

Fel meddelandestruktur

Graph API-fel har en formaterad text som består av en HTTP-statuskod, ett meddelande och värden. Använd egenskaperna för brödtexten fel i din felhantering logik.

Obs: vissa HTTP-svar kan inte innehålla svarstexten code-meddelande-värden eftersom begäran dirigeras via proxy och gateway-tjänster. Se till att inkludera standard logik som kan hantera felen baserat på HTTP-statuskoden enbart.

Följande är ett exempel på ett 400 Request_BadRequest för HTTP-fel.

 HTTP/1.1 400 Bad Request
 Content-Type: application/json;odata=minimalmetadata;charset=utf-8
 request-id: ddca4a7e-02b1-4899-ace1-19860901f2fc
 Date: Tue, 02 Jul 2013 01:48:19 GMT
 …
 
 {
     "odata.error" : {
         "code" : "Request_BadRequest",
         "message" : {
             "lang" : "en",
             "value" : "A value is required for property 'mailNickname' of resource 'Group'."
         },
     "values" : null
    }
 }

Varje meddelandetexten har koden, meddelandet och egenskaper för värden.

  • Koden: utforma din felhantering logik att Förgrena baserat på koden.

    "code" : "Request_BadRequest"

  • Meddelandet: en tuppel för språk-värde som representerar ett läsbart felmeddelande. Innehållet är i värdefältet. I följande exempel, misslyckas denna begäran eftersom värdet för den mailNickname egenskapen saknas.

    "message" : {
     "lang" : "en",
     "value" : "A value is required for property 'mailNickname' of resource 'Group'."
}

  • Värden: en samling av namn/värde-par som ger mer information om felet. I följande exempel ingår inga värden.

    "values" : null

Felkod referens

HTTP-felkoder

I följande tabell visas Graph API felkoder, felmeddelanden och åtgärder att tänka på när du korrigerar fel.

I allmänhet HTTP 500-serien fel besvara omförsök, helst fördelade över allt länge tidsintervall (”försök igen med ett intervall som inte”) och med en slumpmässig distribution faktor. 400-serien felen indikerar ett problem som måste åtgärdas innan du försöker igen.

HTTP-statuskod Felkod Felmeddelande Information
400 Directory_ExpiredPageToken Värdet sidan token har upphört att gälla och kan inte längre inkluderas i din begäran.
400 Directory_ResultSizeLimitExceeded Resultatet storleksgränsen har överskridits Begäran kan inte utföras eftersom den är associerad med för många resultat. Detta fel uppstår mycket sällan.
400 DomainVerificationCodeNotFound Verifiering av domän misslyckas eftersom verifieringsprocessen inte kan hitta TXT-posten med matchande Verifieringskod.
400 ObjectConflict Domännamnet finns redan i en overifierade domän i det här företaget.
400 ObjectConflict Domännamnet finns redan i en verifierad domän i det här företaget.
400 ObjectInUse Det går inte att ta bort domänen som för närvarande refereras av en användare, grupp eller flera program
400 ObjectPendingDeletion Det går inte att verifiera en domän som kommer att tas bort.
400 ObjectPendingTakeover Det går inte att ta bort en domän håller på att en klient övertag
400 Request_BadRequest Felaktig begäran. Åtgärda begäran innan du försöker igen. Anger ett fel i begäran, till exempel ett ogiltigt värde för egenskap eller ett argument som inte stöds av frågan. Åtgärda begäran innan du försöker igen.
400 Request_DataContractVersionMissing Data kontraktet version parameter saknas. Med api-versionen som en frågeparameter med alla begäranden.
400 Request_InvalidDataContractVersion Den angivna api-versionen är ogiltig. Värdet måste exakt matcha en version som stöds.
400 Request_InvalidRequestUrl Url-begäran var ogiltigt. Begäran ska vara som /tenantdomainname/Entity eller /$metadata. Klientdomännamn kan vara någon av de verifierade, overifierade domännamn eller kontext-id.
400 Request_UnsupportedQuery GET-begäran stöds inte. Korrigera parametrarna och försök igen.
401 Authentication_ExpiredToken Åtkomst-token har upphört att gälla. Förnya det innan du skickar begäran. Åtkomst-token har upphört att gälla. Förnya token och skicka sedan igen.
401 Authentication_MissingOrMalformed Åtkomst-Token saknas eller har fel format. Access_token värdet i authorization-huvud är felaktig eller saknas. Det här värdet krävs. Använd värdet i token för autentisering.
401 Authorization_IdentityDisabled Det anropande programmet säkerhetsobjekt är inaktiverad. Huvudnamn som anges i åtkomsttoken är i katalogen, men är inaktiverad. Aktivera kontot i katalogen på nytt och försök igen.
401 Authorization_IdentityNotFound Det gick inte att upprätta identiteten för det anropande programmet. Huvudnamn som anges i den åtkomst-token hittades inte i katalogen. Detta kan inträffa eftersom token är inaktuell, objektet har tagits bort från katalogen eller katalogsynkronisering är fördröjd.
403 Authentication_Unauthorized Obehörig begäran. Token innehåller anspråk för ogiltig eller stöds inte. Hämta token för begäran igen och försök sedan begäran.
403 Authorization_RequestDenied De angivna autentiseringsuppgifterna har inte tillräcklig behörighet för att göra denna begäran. Begäran nekades på grund av otillräcklig behörighet. Till exempel saknar ett huvudnamn för icke-administrativa behörighet att ta bort en resurs.
403 Directory_QuotaExceeded Kvotgräns för directory-objekt för den {tenantName} har överskridits. Be din administratör för att öka kvotgränsen eller ta bort objekt för att minska kvoten som används. En katalog kvot har överskridits. Klienten kanske har för många objekt eller objekt har för många värden. Detta inträffar även när för många objekt har skapats på för objektet. Öka antalet högsta tillåtna objekt för klient- eller principal eller minska antalet värden som ingår i denna begäran skapa/uppdatera.
404 Directory_ObjectNotFound Det gick inte att läsa företagsinformation från katalogen.
404 Request_ResourceNotFound Resursen {resource} finns inte eller något av dess efterfrågade referensegenskapen objekt finns inte. Resursen som identifieras av URI: N finns inte. Ändra värdet och försök sedan begäran.
409 Request_MultipleObjectsWithSameKeyValue En enskild resurs förväntades för resultatet, men flera resurser hittades. Uppdatera objekt för att lösa konflikten. Det här felet kan inträffa när det finns två eller flera objekt som har samma nyckelvärde, t.ex. när två användare ha samma UserPrincipalName.
429 För många begäranden. Det här felet uppstår när begäranden begränsas. Föreslagna väntetiden returneras värdet försök igen efter för rubriken. Försök begäran efter en väntan på det rekommenderade antalet sekunder.
500 Service_InternalServerError Påträffade ett internt serverfel. Internt serverfel när begäran bearbetades.
502 [All] “... Tjänsten tillgänglig... ” En server som fungerar som en gateway eller proxy påträffade ett fel från en annan server vid bearbetning av begäran. Vänta några minuter och försök sedan begäran.
503 Directory_ConcurrencyViolation Fel på grund av samtidiga begäranden som görs till klienten. Vänta en kort stund och försök igen.
503 Ett fel uppstod under verifiering av DNS (Obs: kan orsakas av olika skäl, t.ex. DNS är för närvarande inte tillgängligt).
Authentication_Unknown Internt serverfel. Den här felkoden används när det inte gäller andra felkoder.
Authentication_UnsupportedTokenType Typ av token som presenteras hanteras inte. Ägar-token stöds. Token-typer stöds inte. Ändra tokentypen innan du försöker begäran igen.
Directory_BindingRedirection Klient-information är inte tillgänglig lokalt. Använd följande URL: er för att hämta information om. När klienten partitionen inte är tillgänglig i datacentret måste klienter ansluta till den URl som returnerades i svaret.
Directory_BindingRedirectionInternalServerError Klient-information är inte tillgänglig lokalt. Ett internt fel uppstod vid försök att fylla i de närmaste datacenter-slutpunkterna. När ett undantag för omdirigering av bindning uppstår fylls listan över närmaste datacenter slutpunkter för tjänsten. Det här felet indikerar ett undantag när listan fylldes. Frågan och försök igen.
Directory_CompanyNotFound Det gick inte att läsa företagsinformation från katalogen. Ett fel uppstod vid inläsning av företagets information från katalogtjänsten.
Directory_ReplicaUnavailable Den primära repliken är inte tillgänglig. Försök igen utan någon replik session key-huvud. Utelämna huvudet x-ms-replik-sessionsnyckel, och försök sedan igen.
Headers_DataContractVersionMissing Data servicekontrakt version-huvud saknas. Inkludera x-ms-dirapi-data-contract-version i begäran. Kontraktet klientversionen saknas i begäran.
Headers_HeaderNotSupported Huvudet {0} stöds inte för närvarande. Begäran innehåller ett HTTP-huvud som inte stöds. Ändra rubriken och försök sedan igen.
Request_InvalidReplicaSessionKey Replik sessionsnyckeln som angetts är inte giltig. Åtgärda sessionsnyckeln replik och försök sedan igen.
Request_ThrottledPermanently Din begäran har begränsats permanent. Kontakta supporten om du vill adress problemet. Klienten överskreds flera gånger och beständigt tokenbegäran hastighet. Begäranden från innehavaren avvisas förrän tjänsten omförhandlas. Kontakta Microsoft Support för hjälp.

Ytterligare resurser