Adminisztrációs API válasz- és hibaszerződése

Ez a fájl egészíti ki a Végpontreferencia összes végpontjának válaszszerződését. A sikertörzset a végpont sorában, minden közös vagy végpontspecifikus sikertelen törzset az alábbi táblázatokban talál. A hibák alapértelmezetten több kompatibilitási formát használnak; a hívók egységes univerzális burkolót választhatnak.

Opcionális strukturált hibaburkoló

Bármely végponton elküldheti ezt a kérésfejlécet:

X-Error-Format: envelope

Az összehasonlítás a szélső szóközök nélkül, kis- és nagybetűk megkülönböztetése nélkül történik. Ennél a pontos értéknél minden 400 vagy magasabb állapotú JSON-válasz így alakul át:

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

Példa egy alapértelmezett érvényesítési törzs átalakítására:

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

Az átalakítási szabályok pontosak:

• A(z) validationErrors értékből details.fields, a(z) code értékből VALIDATION_FAILED lesz akkor is, ha az alapértelmezett törzs tartománykódot is tartalmazott.
• Érvényesítési mezők hiányában a rendszer megtartja az alapértelmezett legfelső szintű code értéket.
• A(z) error, message, validationErrors és code kivételével minden más legfelső szintű tulajdonság a(z) details alá kerül; például a jelentésexport limit értékéből details.limit lesz.
• A karakterlánc típusú legfelső szintű error értékből message lesz. Ha nincs ilyen, az állapothoz tartozó tartalékérték érvényesül.
• A tartalékkódok: AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 és más besorolatlan 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) és INTERNAL_ERROR (más 5xx, beleértve a(z) 503 esetet).
• A(z) requestId a pontos X-Request-Id válaszfejléc. A hívó által megadott kérésazonosítót csak akkor használja a rendszer, ha a szélső szóközök eltávolítása után megfelel a(z) [A-Za-z0-9._:-]{1,128} mintának; máskülönben a szerver UUID-t generál.

Az átalakítás nem módosítja az állapotot vagy a nem törzshöz tartozó fejléceket. Az idempotens újrajátszásokra is érvényes az újrajátszási kérés X-Error-Format fejléce szerint. A bináris sikerválaszok binárisak maradnak; JSON-hibáik burkolót kapnak. A további táblázatok az alapértelmezett törzseket mutatják; a fenti szabályok alkalmazásával megkapjuk minden sor másik lehetséges választörzsét.

Válaszjelölések

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

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

PlainError = { error: string }

A(z) error és az érvényesítési üzenet szövege leíró jellegű, nem stabil programozott megkülönböztető. Ha van code, az alapján ágaztasson el. A kérésérvényesítés 422 ValidationError választ ad; teljes objektum érvényesítése { "validationErrors": {} } értéket eredményezhet, ha nincs azonosított egyedi mező. Az érvénytelen JSON és váratlan hibák az alább látható globális 500 PlainError választ adják.

Minden JSON-példa pontos törzsszerkezetet mutat. A(z) <message> formában megadott szöveg a visszaadott érvényesítési vagy műveleti üzenet, és JSON-karakterlánc, nem szó szerinti, csúcsos zárójelbe tett érték.

Kérések feldolgozási sorrendje

A kérések feldolgozási sorrendje:

1. munkaterület-tokenek beállítása és hitelesítése;
2. gazdaházirend és token-/munkaterület-sebességkorlátok;
3. aktuális csomagjogosultságok szűrése;
4. minden módosításnál idempotencia-ellenőrzés/foglalás;
5. végponthatókör-ellenőrzés, kérésérvényesítés és a kért művelet.

Ezért az érvényes, de elégtelen hatókörű tokennel küldött módosításhoz is kötelező a(z) Idempotency-Key. A befejezett 403, 404, 409 vagy 422 módosítás válasza ugyanahhoz a kulcshoz/kéréshez újrajátszható.

Hitelesítési, házirend- és sebességkorlátozási válaszok

Ezek a válaszok minden regisztrált /v2/admin végponton előfordulhatnak a végpontspecifikus feldolgozás előtt.

Az API-hozzáférés minden csomagban benne van. A munkaterület gazdájának adminApiEnabled beállítását kikapcsolva 404 a válasz; egy további funkciójogosultság elvesztése csak az érintett hatóköröket távolítja el. Az így keletkező hatókörmegtagadás az alábbi választ használja, nem tokenfrissítési folyamatot.

Hatókör-, idempotencia-, feldolgozási, tulajdonlási és váratlan hibák

Az erőforrásútvonal-azonosítóknak pozitív számoknak kell lenniük. A nem pozitív vagy nem numerikus :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId vagy :localUserId érték 422 ValidationError választ ad, nem 400 választ.

Helyszín- és teljesítménykezelési hibák

Töltőhibák

A(z) mapChargerErrors() a töltő létrehozásához/frissítéséhez, hitelesítő adataihoz, csatlakozóbeállításaihoz, nyilvános listázásához, QR-tartalom feloldásához, konfigurációmódosításhoz/újratöltéshez, firmware-indításhoz, mind a négy alapvető parancshoz és az összesített ütemezés kéréséhez használatos.

Az egyszerű olvasási műveletek csak a közös 401/403/404/429/500/503 válaszokat és a(z) 422 lekérdezés-/útvonalérvényesítést adják. A töltőtörlés a közös 500 PlainError választ adhatja, ha konkrétabb hibaválasz nélkül sikertelen.

Jelentéshibák

A sikeres export bináris; minden exporthiba JSON marad.

Tarifahibák

Töltésiprofil-hibák

Felhasználói tartományhibák

A mezőt azonosító felhasználóérvényesítési hibák ValidationError és code értéket használnak; más felhasználói hibák CodedError típust használnak. Minden hiányzóerőforrás-eset a közös, felderítést megakadályozó RESOURCE_NOT_FOUND választ használja.

A(z) POST /users/invitations a törzs feldolgozása után a közös 403 INSUFFICIENT_SCOPE választ is adhatja, ha a(z) users:access hiányzik, vagy ha RFID-t adtak meg, és a(z) users:rfid hiányzik. A helyifelhasználó-végpontok minden szükséges hatókört felsorolnak a Végpontreferenciában.

A felhasználói hibakódok alkalmazása:

Az ezekben a csoportokban előforduló minden tulajdonlási és hiányzóerőforrás-eredmény, beleértve a(z) POST /users végponton a nem regisztrált e-mail-címet is, a közös 404 RESOURCE_NOT_FOUND törzset használja.

Törzs nélküli és újrajátszott válaszok

A sikeres 204 válasz nem tartalmaz törzset. Ez minden olyan dokumentált törlésre érvényes, amely 204 empty választ sorol fel. A befejezett idempotens újrajátszás beállítja a(z) Idempotency-Replayed: true értéket, és a tárolt állapotot/törzset használja; 204 esetén a HTTP-válasz törzs nélküli marad. Az API soha nem ad JSON-sikerobjektumot dokumentált 204 művelethez.