Kontrakt odpovědí a chyb administračního API

Tento soubor doplňuje kontrakt odpovědí pro každý endpoint v Referenci endpointů. Úspěšné tělo najdete v řádku endpointu a všechna sdílená či specifická neúspěšná těla v tabulkách níže. Ve výchozím stavu mají chyby několik kompatibilních tvarů; volající může zvolit jednu univerzální obálku.

Volitelná strukturovaná obálka chyb

Na libovolný endpoint odešlete tuto hlavičku požadavku:

X-Error-Format: envelope

Hodnota se porovnává po oříznutí mezer bez rozlišení velikosti písmen. Při této přesné hodnotě se každá odpověď JSON se stavem 400 nebo vyšším převede na:

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

Příklad převodu výchozího validačního těla:

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

Pravidla převodu jsou přesná:

• validationErrors se změní na details.fields a code na VALIDATION_FAILED, i když výchozí tělo mělo také doménový kód.
• Výchozí code na nejvyšší úrovni zůstane zachováno, pokud nejsou žádná validační pole.
• Ostatní vlastnosti nejvyšší úrovně kromě error, message, validationErrors a code se přesunou do details; například limit exportu přehledu se změní na details.limit.
• Řetězcové error na nejvyšší úrovni se změní na message. Pokud chybí, použije se náhradní text podle stavu.
• Náhradní kódy jsou AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 a další nezařazené 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) a INTERNAL_ERROR (ostatní 5xx včetně 503).
• requestId je přesná hlavička odpovědi X-Request-Id. ID požadavku dodané volajícím se použije jen tehdy, odpovídá-li po oříznutí [A-Za-z0-9._:-]{1,128}; jinak server vygeneruje UUID.

Tento převod nemění stav ani hlavičky nesouvisející s tělem. Platí také pro idempotentní přehrání podle hlavičky X-Error-Format opakovaného požadavku. Binární úspěšné odpovědi zůstávají binární; jejich chyby JSON se zabalí do obálky. Další tabulky uvádějí výchozí těla; použitím pravidel výše získáte druhé možné tělo odpovědi pro každý řádek.

Zápis odpovědí

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

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

PlainError = { error: string }

error a text ověřovací zprávy jsou popisné, nikoli stabilní programové rozlišovače. Větvení provádějte podle code, je-li přítomno. Ověření požadavku vrací 422 ValidationError; ověření celého objektu může vytvořit { "validationErrors": {} }, pokud není určeno jednotlivé pole. Neplatný JSON a neočekávaná selhání vracejí globální 500 PlainError uvedené níže.

Všechny příklady JSON jsou přesné tvary těla. Text uvedený jako <message> je vrácená validační nebo provozní zpráva a jde o JSON řetězec, nikoli doslovnou hodnotu v lomených závorkách.

Pořadí zpracování požadavku

Požadavky se zpracovávají v tomto pořadí:

1. konfigurace a ověřování tokenu pracovního prostoru;
2. pravidla hostitele a limity požadavků tokenu/pracovního prostoru;
3. filtrování aktuálních nároků;
4. pro každou změnu ověření/získání idempotence;
5. kontroly rozsahů endpointu, ověření požadavku a požadovaná operace.

I změna s platným tokenem a nedostatečným rozsahem musí poslat Idempotency-Key. Dokončenou odpověď změny 403, 404, 409 nebo 422 lze přehrát pro stejný klíč a požadavek.

Odpovědi ověření, pravidel a omezení požadavků

Tyto odpovědi se mohou objevit na každém registrovaném endpointu /v2/admin před jeho specifickým zpracováním.

Přístup API je v každém balíčku. Vypnutí nastavení adminApiEnabled u hostitele vrací 404; ztráta dalšího funkčního nároku odebere jen dotčené rozsahy. Odmítnutí rozsahu používá níže uvedenou odpověď, nikoli obnovení tokenu.

Rozsah, idempotence, parsování, vlastnictví a neočekávaná selhání

ID prostředků v cestě musí být kladná čísla. Nekladné nebo nečíselné :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId nebo :localUserId vrací 422 ValidationError, nikoli 400.

Chyby lokalit a řízení výkonu

Chyby nabíječek

mapChargerErrors() se používá při vytváření/aktualizaci nabíječky, přihlašovacích údajích, nastavení konektorů, veřejném zveřejnění, rozlišení obsahu QR, změně/znovunačtení konfigurace, spuštění firmwaru, všech čtyřech základních příkazech a požadavku na složený rozvrh.

Běžné operace čtení vracejí pouze sdílené odpovědi 401/403/404/429/500/503 a ověření dotazu/cesty 422. Smazání nabíječky může vrátit sdílenou chybu 500 PlainError, pokud selže bez konkrétnější chybové odpovědi.

Chyby přehledů

Úspěšný export je binární; všechny chyby exportu zůstávají JSON.

Chyby tarifů

Chyby nabíjecích profilů

Chyby uživatelské domény

Chyby ověření uživatele určující pole používají ValidationError a code; ostatní chyby uživatele používají CodedError. Všechny případy chybějícího prostředku používají sdílenou odpověď RESOURCE_NOT_FOUND, která neprozrazuje existenci prostředků.

POST /users/invitations může po parsování těla také vrátit sdílené 403 INSUFFICIENT_SCOPE, pokud chybí users:access, nebo pokud bylo předáno RFID a chybí users:rfid. Endpointy místních uživatelů uvádějí každý požadovaný rozsah v Referenci endpointů.

Chybové kódy uživatelů se používají takto:

Všechny výsledky vlastnictví a chybějících zdrojů v těchto skupinách, včetně neregistrovaného e-mailu na POST /users, používají společné tělo 404 RESOURCE_NOT_FOUND.

Odpovědi bez těla a opakované odpovědi

Úspěšná odpověď 204 nemá tělo. Platí to pro každé dokumentované mazání uvádějící 204 empty. Dokončené idempotentní opakování nastaví Idempotency-Replayed: true a použije uložený stav a tělo; u 204 zůstává HTTP odpověď bez těla. API nikdy nevrací úspěšný JSON objekt pro dokumentovanou operaci 204.