Kontrakt for svar og fejl i Admin API

Denne fil fuldender svarkontrakten for hvert endpoint i Endpointreference. Læs endpointrækken om vellykket svartekst og tabellerne nedenfor om alle fælles eller endpointspecifikke svartekster ved manglende succes. Som standard bruger fejl flere kompatibilitetsstrukturer; klienter kan vælge én universel omslutning.

Valgfri struktureret fejlomslutning

Send denne anmodningsheader til et hvilket som helst endpoint:

X-Error-Format: envelope

Ved værdisammenligningen fjernes omgivende mellemrum, og store og små bogstaver skelnes ikke. Med netop denne værdi konverteres alle JSON-svar med status 400 eller højere til:

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

Eksempel på konvertering af en standardvalideringssvartekst:

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

Konverteringsreglerne er præcise:

• validationErrors bliver til details.fields, og code bliver til VALIDATION_FAILED, også når standardsvarteksten havde en domænekode.
• En code på øverste niveau i standardsvaret bevares, når der ikke er valideringsfelter.
• Andre egenskaber på øverste niveau bortset fra error, message, validationErrors og code flyttes til details; ved rapporteksport bliver limit f.eks. til details.limit.
• En error af typen streng på øverste niveau bliver til message. Hvis den ikke findes, bruges statuskodens standardtekst.
• Standardkoder er AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 og andre uklassificerede 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) og INTERNAL_ERROR (andre 5xx, inklusive 503).
• requestId er den nøjagtige X-Request-Id-svarheader. Et anmodnings-ID angivet af klienten bruges kun, når det matcher [A-Za-z0-9._:-]{1,128} efter fjernelse af omgivende mellemrum; ellers genererer serveren en UUID.

Denne transformation ændrer ikke status eller headere uden for svarteksten. Den gælder også ved idempotente gentagelser i henhold til gentagelsesanmodningens X-Error-Format-header. Binære svar ved succes forbliver binære; deres JSON-fejl omsluttes. De øvrige tabeller viser standardsvarteksterne; anvendelse af reglerne ovenfor giver den anden mulige svartekst for hver række.

Notation for svar

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

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

PlainError = { error: string }

error og valideringsmeddelelser er beskrivende tekst, ikke en stabil programmatisk skelnen. Basér logikken på code, når den er til stede. Anmodningsvalidering returnerer 422 ValidationError; validering af et helt objekt kan give { "validationErrors": {} }, når intet enkelt felt identificeres. Ugyldig JSON og uventede fejl returnerer den globale 500 PlainError vist nedenfor.

Alle JSON-eksempler viser de nøjagtige strukturer for anmodnings- og svartekster. Tekst vist som <message> er den returnerede validerings- eller handlingsmeddelelse og er en JSON-streng, ikke en bogstavelig værdi med vinkelparenteser.

Rækkefølge for anmodningsbehandling

Anmodninger behandles i denne rækkefølge:

1. konfiguration og autentificering af arbejdsområdetokens;
2. værtspolitik og anmodningsgrænser for token/arbejdsområde;
3. filtrering efter aktuelle rettigheder;
4. idempotensvalidering og reservation ved hver ændringshandling;
5. kontrol af endpointscopes, anmodningsvalidering og den ønskede handling.

En ændringsanmodning med et gyldigt token, men utilstrækkelige scopes, skal derfor stadig sende Idempotency-Key. Et fuldført svar med 403, 404, 409 eller 422 på en ændringsanmodning kan gentages med samme nøgle og anmodning.

Svar om autentificering, politik og anmodningsbegrænsning

Disse svar kan forekomme på alle registrerede /v2/admin-endpoints før endpointspecifik behandling.

API-adgang er inkluderet i alle planer. Hvis adminApiEnabled-indstillingen på arbejdsområdets vært deaktiveres, returneres 404; tab af en ekstra funktionsrettighed fjerner kun de berørte scopes. Den efterfølgende afvisning af scope bruger svaret nedenfor, ikke et tokenfornyelsesforløb.

Fejl i scopes, idempotens, fortolkning og ejerskab samt uventede fejl

Ressource-ID'er i stien skal være positive tal. Ikke-positive eller ikke-numeriske værdier for :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId eller :localUserId returnerer 422 ValidationError, ikke 400.

Fejl i steder og strømstyring

Laderfejl

mapChargerErrors() bruges ved oprettelse/opdatering af lader, legitimationsoplysninger, stikindstillinger, offentlig visning, QR-dataopløsning, konfigurationsændring/genindlæsning, firmwarestart, alle fire grundkommandoer og anmodning om sammensat tidsplan.

Almindelige læsehandlinger returnerer kun de fælles 401/403/404/429/500/503-svar samt 422 ved validering af forespørgsel eller sti. Sletning af en lader kan returnere den fælles 500 PlainError, hvis sletningen mislykkes uden et mere specifikt fejlsvar.

Rapportfejl

En vellykket eksport er binær; alle eksportfejl forbliver JSON.

Tariffejl

Fejl i ladeprofiler

Brugerdomænefejl

Brugervalideringsfejl, som identificerer et felt, bruger ValidationError sammen med code; andre brugerfejl bruger CodedError. Alle tilfælde af manglende ressourcer bruger det fælles RESOURCE_NOT_FOUND-svar, som ikke afslører ressourcens eksistens.

POST /users/invitations kan også returnere den fælles 403 INSUFFICIENT_SCOPE efter fortolkning af anmodningsteksten, hvis users:access mangler, eller hvis en RFID blev angivet, og users:rfid mangler. Endpoints til lokale brugere viser alle påkrævede scopes i Endpointreference.

Brugerfejlkoderne gælder som følger:

Alle ejerskabs- og manglende-ressource-resultater i disse grupper, herunder en uregistreret e-mailadresse i POST /users, bruger den fælles 404 RESOURCE_NOT_FOUND-svartekst.

Svar uden svartekst og ved gentagelse

Et vellykket 204-svar har ingen svartekst. Det gælder alle dokumenterede sletninger, der angiver 204 empty. En fuldført idempotent gentagelse sætter Idempotency-Replayed: true og bruger den gemte status og svartekst; ved 204 forbliver HTTP-svaret uden svartekst. API'et returnerer aldrig et JSON-objekt ved en vellykket dokumenteret 204-handling.