Kontrakt för svar och fel i Admin API

Den här filen kompletterar svarskontraktet för varje endpoint i Endpointreferens. Läs endpointraden för den lyckade svarskroppen och tabellerna nedan för varje gemensam eller endpointspecifik kropp vid fel. Som standard använder fel flera kompatibilitetsstrukturer; klienter kan välja en universell omslutning.

Valfri strukturerad felomslutning

Skicka den här anropsheadern till valfri endpoint:

X-Error-Format: envelope

Vid värdejämförelse tas omgivande blanksteg bort och ingen skillnad görs mellan gemener och versaler. Med exakt detta värde konverteras varje JSON-svar med status 400 eller högre till:

ErrorEnvelope = {
  error: {
    code: string,
    message: string,
    details: Record<string, unknown>,
    requestId: string
  }
}

Exempel på konvertering av en standardvalideringskropp:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid request",
    "details": {
      "fields": {
        "name": ["String must contain at least 1 character(s)"]
      }
    },
    "requestId": "integration-42"
  }
}

Konverteringsreglerna är exakta:

• validationErrors blir details.fields och code blir VALIDATION_FAILED även när standardkroppen också hade en domänkod.
• Ett code på översta nivån i standardsvaret behålls när det inte finns några valideringsfält.
• Andra egenskaper på översta nivån, utom error, message, validationErrors och code, flyttas till details; vid rapportexport blir exempelvis limit till details.limit.
• Ett error av typen sträng på översta nivån blir message. Om det saknas används statuskodens reservtext.
• Reservkoderna är AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 och andra oklassificerade 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) och INTERNAL_ERROR (övriga 5xx, inklusive 503).
• requestId är den exakta X-Request-Id-svarsheadern. Ett anrops-ID från klienten används bara när det matchar [A-Za-z0-9._:-]{1,128} efter att omgivande blanksteg har tagits bort; annars skapar servern ett UUID.

Omvandlingen ändrar inte status eller headrar utanför svarskroppen. Den gäller också idempotenta upprepningar enligt upprepningsanropets X-Error-Format-header. Binära framgångssvar förblir binära; deras JSON-fel omsluts. Övriga tabeller visar standardkropparna; reglerna ovan ger den andra möjliga svarskroppen för varje rad.

Svarsnotation

ValidationError = {
  validationErrors: Record<string, string[]>,
  code?: string
}

CodedError = {
  error: string,
  code: string,
  // a route may add fields explicitly listed below
}

PlainError = { error: string }

error och valideringsmeddelanden är beskrivande text, inte en stabil programmatisk avskiljare. Basera logiken på code när den finns. Anropsvalidering returnerar 422 ValidationError; validering av ett helt objekt kan ge { "validationErrors": {} } när inget enskilt fält identifieras. Ogiltig JSON och oväntade fel returnerar det globala 500 PlainError som visas nedan.

Alla JSON-exempel visar exakta kroppsstrukturer. Text som visas som <message> är det returnerade validerings- eller åtgärdsmeddelandet och är en JSON-sträng, inte ett bokstavligt värde med vinkelparenteser.

Ordning för anropsbehandling

Anrop behandlas i den här ordningen:

1. konfiguration och autentisering av arbetsytetoken;
2. värdpolicy och anropsgränser för token/arbetsyta;
3. filtrering efter aktuella rättigheter;
4. idempotensvalidering och reservation för varje ändringsåtgärd;
5. kontroll av endpointbehörigheter, anropsvalidering och den begärda åtgärden.

En ändringsbegäran med en giltig token men otillräckliga behörighetsområden måste därför fortfarande skicka Idempotency-Key. Ett slutfört ändringssvar med 403, 404, 409 eller 422 kan upprepas för samma nyckel och anrop.

Svar för autentisering, policy och anropsbegränsning

Dessa svar kan förekomma på varje registrerad /v2/admin-endpoint före endpointspecifik behandling.

API-åtkomst ingår i alla planer. Om arbetsytans värd stänger av inställningen adminApiEnabled returneras 404; om en ytterligare funktionsrättighet försvinner tas endast berörda behörighetsområden bort. Den följande nekade behörigheten använder svaret nedan, inte ett flöde för att förnya token.

Fel i behörighetsområden, idempotens, tolkning, ägarskap och oväntade fel

Resurs-ID:n i sökvägen måste vara positiva tal. Ett icke-positivt eller icke-numeriskt :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId eller :localUserId returnerar 422 ValidationError, inte 400.

Fel för platser och effektstyrning

Laddarfel

mapChargerErrors() används vid skapande/uppdatering av laddare, autentiseringsuppgifter, kontaktinställningar, publik listning, upplösning av QR-data, ändring/omläsning av konfiguration, firmwarestart, alla fyra grundkommandon och begäran om sammansatt schema.

Vanliga läsåtgärder returnerar endast de gemensamma svaren 401/403/404/429/500/503 samt 422 för validering av fråga och sökväg. Borttagning av en laddare kan returnera det gemensamma 500 PlainError om borttagningen misslyckas utan ett mer specifikt felsvar.

Rapportfel

En lyckad export är binär; alla exportfel förblir JSON.

Tarifffel

Fel för laddprofiler

Användardomänfel

Användarvalideringsfel som identifierar ett fält använder ValidationError tillsammans med code; övriga användarfel använder CodedError. Alla fall av saknad resurs använder det gemensamma RESOURCE_NOT_FOUND-svaret som inte avslöjar resursens existens.

POST /users/invitations kan också returnera det gemensamma 403 INSUFFICIENT_SCOPE efter kroppstolkning om users:access saknas, eller om RFID angavs och users:rfid saknas. Endpoints för lokala användare listar alla obligatoriska behörighetsområden i Endpointreferens.

Användarfelkoderna gäller enligt följande:

Alla utfall för ägarskap och saknade resurser i dessa grupper, även en oregistrerad e-postadress i POST /users, använder den gemensamma svarskroppen 404 RESOURCE_NOT_FOUND.

Svar utan kropp och upprepade svar

Ett lyckat 204-svar saknar svarskropp. Det gäller varje dokumenterad borttagning som anger 204 empty. En slutförd idempotent upprepning sätter Idempotency-Replayed: true och använder sparad status och svarskropp; för 204 förblir HTTP-svaret utan kropp. API:et returnerar aldrig ett JSON-objekt för en lyckad dokumenterad 204-åtgärd.