Pogodba odgovorov in napak Admin API

Ta datoteka dopolnjuje pogodbo odgovorov za vsako končno točko v Referenci končnih točk. Za uspešno telo preberite vrstico končne točke, za vsa skupna ali posebna neuspešna telesa pa spodnje tabele. Napake privzeto uporabljajo več združljivostnih oblik; klicatelji lahko izberejo eno univerzalno ovojnico.

Neobvezna strukturirana ovojnica napak

Kateri koli končni točki pošljite to glavo zahteve:

X-Error-Format: envelope

Primerjava vrednosti odstrani robne presledke in ne razlikuje velikosti črk. Pri tej natančni vrednosti se vsak odgovor JSON s stanjem 400 ali višjim pretvori v:

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

Primer pretvorbe privzetega telesa preverjanja:

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

Pravila pretvorbe so natančna:

• validationErrors postane details.fields in code postane VALIDATION_FAILED, tudi če je privzeto telo imelo domensko kodo.
• Privzeti code na najvišji ravni se ohrani, kadar ni polj za preverjanje veljavnosti.
• Druge lastnosti najvišje ravni razen error, message, validationErrors in code se premaknejo v details; na primer limit izvoza poročila postane details.limit.
• Niz error na najvišji ravni postane message. Če ga ni, se uporabi nadomestna vrednost za stanje.
• Nadomestne kode so AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 in drugi nerazvrščeni 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) in INTERNAL_ERROR (drugi 5xx, vključno z 503).
• requestId je natančna glava odgovora X-Request-Id. ID zahteve, ki ga poda klicatelj, se uporabi samo, če po obrezovanju ustreza [A-Za-z0-9._:-]{1,128}; sicer strežnik ustvari UUID.

Ta pretvorba ne spreminja stanja ali glav, nepovezanih s telesom. Velja tudi za idempotentne ponovitve glede na glavo X-Error-Format ponovljene zahteve. Binarni uspešni odgovori ostanejo binarni; njihove napake JSON dobijo ovojnico. Preostale tabele prikazujejo privzeta telesa; zgornja pravila dajo drugo možno telo odgovora za vsako vrstico.

Oznake odgovorov

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

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

PlainError = { error: string }

error in besedilo sporočila preverjanja sta opisna, ne stabilna programska razlikovalnika. Razvejite po code, kadar je prisoten. Preverjanje zahteve vrne 422 ValidationError; preverjanje celotnega objekta lahko vrne { "validationErrors": {} }, kadar posamezno polje ni določeno. Neveljaven JSON in nepričakovane napake vrnejo spodaj prikazani globalni 500 PlainError.

Vsi primeri JSON prikazujejo natančne oblike teles. Besedilo <message> je vrnjeno sporočilo preverjanja ali operacije in je niz JSON, ne dobesedna vrednost v kotnih oklepajih.

Vrstni red obdelave zahtev

Zahteve se obdelajo v tem vrstnem redu:

1. konfiguracija in overjanje žetona delovnega prostora;
2. pravilnik gostitelja in omejitve zahtev žetona/delovnega prostora;
3. filtriranje trenutnih pravic;
4. za vsako spremembo preverjanje/rezervacija idempotentnosti;
5. preverjanje obsegov končne točke, preverjanje zahteve in zahtevana operacija.

Zato mora tudi sprememba z veljavnim žetonom s preozkim obsegom poslati Idempotency-Key. Dokončan odgovor spremembe 403, 404, 409 ali 422 je mogoče ponoviti z istim ključem/zahtevo.

Odgovori za overjanje, pravilnike in omejevanje zahtev

Ti odgovori se lahko pojavijo pri vsaki registrirani končni točki /v2/admin pred obdelavo, značilno zanjo.

Dostop API je vključen v vsak paket. Izklop nastavitve adminApiEnabled gostitelja delovnega prostora vrne 404; izguba dodatne pravice do funkcije odstrani samo prizadete obsege. Nastala zavrnitev obsega uporabi spodnji odgovor in ne postopka osveževanja žetona.

Obseg, idempotentnost, razčlenjevanje, lastništvo in nepričakovane napake

ID-ji poti virov morajo biti pozitivna števila. Nepozitivni ali neštevilčni :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId ali :localUserId vrne 422 ValidationError, ne 400.

Napake lokacij in upravljanja moči

Napake polnilnic

mapChargerErrors() se uporablja za ustvarjanje/posodobitev polnilnice, poverilnice, nastavitve priključkov, javno objavo, razreševanje vsebine QR, spremembo/ponovno nalaganje konfiguracije, začetek vdelane programske opreme, vse štiri osnovne ukaze in zahtevo sestavljenega urnika.

Običajne bralne operacije vračajo samo skupne odgovore 401/403/404/429/500/503 in preverjanje poizvedbe/poti 422. Izbris polnilnice lahko vrne skupni 500 PlainError, če ne uspe brez natančnejšega odgovora napake.

Napake poročil

Uspešen izvoz je binaren; vse napake izvoza ostanejo JSON.

Napake tarif

Napake profilov polnjenja

Napake uporabniške domene

Napake preverjanja uporabnikov, ki določajo polje, uporabljajo ValidationError in code; druge uporabniške napake uporabljajo CodedError. Vsi primeri manjkajočih virov uporabljajo skupni nerazkrivajoči odgovor RESOURCE_NOT_FOUND.

POST /users/invitations lahko po razčlenjevanju telesa vrne tudi skupni 403 INSUFFICIENT_SCOPE, če manjka users:access ali če je podan RFID in manjka users:rfid. Končne točke lokalnih uporabnikov navajajo vsak zahtevani obseg v Referenci končnih točk.

Kode uporabniških napak se uporabljajo tako:

Vsi izidi lastništva in manjkajočih virov v teh skupinah, tudi neregistriran e-poštni naslov pri POST /users, uporabljajo skupno telo 404 RESOURCE_NOT_FOUND.

Odgovori brez telesa in ponovljeni odgovori

Uspešen odgovor 204 nima telesa. To velja za vsak dokumentiran izbris, ki navaja 204 empty. Dokončano idempotentno ponavljanje nastavi Idempotency-Replayed: true in uporabi shranjeno stanje/telo; pri 204 odgovor HTTP ostane brez telesa. API nikoli ne vrne uspešnega objekta JSON za dokumentirano operacijo 204.