Kontrakt odpovedí a chýb administrátorského API

Tento súbor dopĺňa kontrakt odpovedí pre každý koncový bod v časti Referenčný prehľad koncových bodov. V riadku koncového bodu nájdete telo úspešnej odpovede a v tabuľkách nižšie každé spoločné alebo špecifické telo neúspešnej odpovede. Chyby predvolene používajú viac tvarov pre kompatibilitu; volajúci si môžu zvoliť jednu univerzálnu obálku.

Voliteľná štruktúrovaná obálka chyby

Na ľubovoľný koncový bod odošlite túto hlavičku požiadavky:

X-Error-Format: envelope

Pri porovnaní hodnoty sa odstránia okrajové medzery a nerozlišujú sa veľké a malé písmená. Pri tejto presnej hodnote sa každá odpoveď JSON so stavom 400 alebo vyšším prevedie na:

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

Príklad konverzie predvoleného validačného tela:

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

Pravidlá konverzie sú presné:

validationErrors sa zmení na details.fields a code na VALIDATION_FAILED, aj keď predvolené telo obsahovalo aj doménový kód.
Predvolené pole code na najvyššej úrovni sa zachová, ak nie sú k dispozícii validačné polia.
Ostatné vlastnosti na najvyššej úrovni okrem error, message, validationErrors a code sa presunú do details; napríklad limit exportu výkazu sa zmení na details.limit.
Textové pole error na najvyššej úrovni sa zmení na message. Ak neexistuje, použije sa predvolená správa pre daný stav.
Záložné kódy sú AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 a ostatné nezaradené 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) a INTERNAL_ERROR (ostatné 5xx vrátane 503).
requestId je presná hlavička odpovede X-Request-Id. ID požiadavky zadané volajúcim sa použije iba vtedy, ak po odstránení okrajových medzier zodpovedá [A-Za-z0-9._:-]{1,128}; inak server vygeneruje UUID.

Táto transformácia nemení stav ani hlavičky nesúvisiace s telom. Uplatňuje sa aj na idempotentné opakovania podľa hlavičky X-Error-Format požiadavky na opakovanie. Binárne úspešné odpovede zostávajú binárne; ich chyby JSON sa vložia do obálky. Zvyšné tabuľky zobrazujú predvolené telá; použitím vyššie uvedených pravidiel získate druhé možné telo odpovede pre každý riadok.

Označenia odpovedí

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 validačnej správy sú opisné, nie stabilné programové rozlišovacie kritériá. Rozhodujte sa podľa code, ak je prítomné. Validácia požiadavky vracia 422 ValidationError; validácia celého objektu môže vytvoriť { "validationErrors": {} }, ak nie je určené konkrétne pole. Neplatný JSON a neočakávané zlyhania vracajú globálne 500 PlainError zobrazené nižšie.

Všetky príklady JSON zobrazujú presné tvary tiel. Text označený ako <message> je vrátená validačná správa alebo správa operácie a je reťazcom JSON, nie doslovnou hodnotou v lomených zátvorkách.

Poradie spracovania požiadaviek

Požiadavky sa spracúvajú v tomto poradí:

konfigurácia a autentifikácia tokenov pracovného priestoru;
pravidlá poskytovateľa a limity frekvencie tokenu/pracovného priestoru;
filtrovanie aktuálnych nárokov;
pri každej zmenovej operácii validácia a rezervácia idempotentného kľúča;
kontroly rozsahov koncového bodu, validácia požiadavky a požadovaná operácia.

Aj zmenová požiadavka s platným tokenom, ktorý nemá dostatočné rozsahy, teda musí odoslať Idempotency-Key. Dokončenú odpoveď zmenovej operácie 403, 404, 409 alebo 422 možno zopakovať pre rovnaký kľúč a požiadavku.

Odpovede autentifikácie, pravidiel a obmedzenia frekvencie požiadaviek

Tieto odpovede sa môžu vyskytnúť na každom registrovanom koncovom bode /v2/admin pred spracovaním špecifickým pre daný bod.

Stav	Kedy	Presné telo	Súvisiace hlavičky
`401`	Chýbajúci, duplicitný, čiarkami spojený token pracovného priestoru, token s inou schémou než Bearer, nesprávne formátovaný, neznámy, expirovaný, odvolaný alebo inak neplatný token	`{ "error": "Unauthorized", "code": "INVALID_WORKSPACE_TOKEN" }`	`WWW-Authenticate: Bearer`, `Cache-Control: no-store`
`404`	Token je platný, ale poskytovateľ jeho pracovného priestoru nemá `adminApiEnabled`	`{ "error": "Not Found" }`	`Cache-Control: no-store`
`429`	Vyčerpal sa limit požiadaviek tokenu alebo pracovného priestoru	`{ "error": "Too many attempts. Please try again later." }`	`Retry-After: <seconds>`
`503`	Autentifikácia tokenu pracovného priestoru je dočasne nedostupná	`{ "error": "Admin API workspace-token configuration is unavailable", "code": "WORKSPACE_API_CONFIG_UNAVAILABLE" }`	—
`503`	Zlyhá vyhľadanie pravidiel poskytovateľa alebo autorizácia aktuálnych nárokov	`{ "error": "Workspace authorization is temporarily unavailable", "code": "WORKSPACE_AUTHORIZATION_UNAVAILABLE" }`	—

Prístup k API je súčasťou každého programu. Vypnutie nastavenia adminApiEnabled u poskytovateľa pracovného priestoru vráti 404; strata dodatočného nároku na funkciu odstráni iba dotknuté rozsahy. Výsledné zamietnutie rozsahu používa odpoveď uvedenú nižšie, nie postup obnovenia tokenu.

Chyby rozsahu, idempotencie, parsovania, vlastníctva a neočakávané zlyhania

Vzťahuje sa na	Stav	Presné telo	Hlavičky/poznámky
Každá trasa po autentifikácii	`403`	`{ "error": "Insufficient workspace-token scope", "code": "INSUFFICIENT_SCOPE" }`	Vracia sa, keď chýba ktorýkoľvek požadovaný rozsah oprávnení.
Každá zmenová operácia	`400`	`{ "error": "Idempotency-Key is required for this operation", "code": "IDEMPOTENCY_KEY_REQUIRED" }`	Kľúč nebol zadaný.
Každá zmenová operácia	`400`	`{ "error": "Exactly one Idempotency-Key is required", "code": "INVALID_IDEMPOTENCY_KEY" }`	Duplicitná hlavička alebo hodnoty spojené čiarkou.
Každá zmenová operácia	`400`	`{ "error": "Idempotency-Key must contain 1 to 255 visible characters", "code": "INVALID_IDEMPOTENCY_KEY" }`	Prázdne, príliš dlhé alebo obsahujúce riadiaci znak.
Každá zmenová operácia	`409`	`{ "error": "Idempotency-Key was already used with a different request", "code": "IDEMPOTENCY_CONFLICT" }`	Rovnaký token/metóda/cesta/kľúč, ale iná URL alebo telo.
Každá zmenová operácia	`409`	`{ "error": "Request is already processing", "code": "IDEMPOTENT_REQUEST_PROCESSING" }`	`Retry-After: 5`.
Každá zmenová operácia	`409`	`{ "error": "Previous request outcome is unknown; verify its effects before attempting the operation again", "code": "IDEMPOTENCY_OUTCOME_UNKNOWN" }`	Predchádzajúca rezervácia spracovania vypršala, spojenie sa uzavrelo alebo požiadavka skončila s `5xx`.
Každá zmenová operácia	`503`	`{ "error": "Idempotency storage unavailable", "code": "IDEMPOTENCY_UNAVAILABLE" }`	API nedokáže skontrolovať ani uložiť záznam idempotencie.
Ľubovoľný koncový bod s neplatnou schémou dopytu, tela alebo cesty	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`	Môže byť prítomných viac polí alebo správ. Volajúci nemôžu zadať `cpoId`; pracovný priestor vždy pochádza z tokenu.
Ľubovoľný chýbajúci vnorený zdroj pracovného priestoru alebo ID z iného pracovného priestoru	`404`	`{ "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }`	Používa sa jednotne, pokiaľ tabuľka nižšie neuvádza inak.
Ľubovoľný koncový bod s neočakávaným zlyhaním	`500`	`{ "error": "Something went wrong" }`	Pri zmenových operáciách neskoršie zopakovanie rovnakého kľúča vráti `409 IDEMPOTENCY_OUTCOME_UNKNOWN`.

ID zdrojov v ceste musia byť kladné čísla. Nekladné alebo nečíselné :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId alebo :localUserId vráti 422 ValidationError, nie 400.

Chyby lokalít a riadenia výkonu

Koncové body	Stav	Presné telo
Vytvorenie/aktualizácia lokality; validácia polí pracovného priestoru	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`
`DELETE /v2/admin/sites/:siteId`, keď lokalita má závislosti	`409`	`{ "error": "<message>", "code": "SITE_NOT_EMPTY" }`
`GET /v2/admin/sites/geocode` neplatné normalizované vyhľadávanie	`400`	`{ "error": "<message>", "code": "INVALID_GEOCODE_QUERY" }`
To isté, plný ohraničený front poskytovateľa	`429`	`{ "error": "<message>", "code": "GEOCODING_BUSY" }`; obsahuje `Retry-After`, keď ho dodá geokodér
To isté, časový limit/zlyhanie poskytovateľa alebo neočakávaná chyba geokodéra	`502`	`{ "error": "<message>", "code": "GEOCODING_UNAVAILABLE" }`; neočakávaná chyba používa `Address search is temporarily unavailable`
`PUT /v2/admin/sites/:siteId/power-management` neplatná konfigurácia topológie/domény	`422`	`{ "error": "<message>", "code": "INVALID_POWER_MANAGEMENT_CONFIGURATION" }`
To isté, odmietnutie OCPP/časový limit, súbeh alebo konflikt zosúladenia	`409`	`{ "error": "<message>", "code": "POWER_MANAGEMENT_CONFLICT" }`

Chyby nabíjačiek

mapChargerErrors() používa vytváranie/aktualizácia nabíjačky, prihlasovacie údaje, nastavenia konektora, verejné zverejnenie, rozlíšenie údajov QR, zmena/opätovné načítanie konfigurácie, spustenie firmvéru, všetky štyri základné príkazy a požiadavka zloženého harmonogramu.

Koncové body	Stav	Presné telo
Ľubovoľná vyššie uvedená operácia so zlyhaním validácie doménových pravidiel	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`
Ľubovoľná vyššie uvedená operácia s konfliktom stavu, jedinečnosti, offline/OCPP, fakturácie, režimu bez identifikátora, konektora alebo pripravenosti	`409`	`{ "error": "<message>", "code": "CHARGER_CONFLICT" }`
`GET /chargers/:chargerId/sessions`, neplatný predvolený alebo výslovný časový rozsah	`422`	`{ "validationErrors": { "from": ["from must be before or equal to to"] } }` alebo `{ "validationErrors": { "from": ["Session range cannot exceed 90 days"] } }`

Bežné operácie čítania vracajú iba spoločné odpovede 401/403/404/429/500/503 a 422 pri validácii dopytu/cesty. Odstránenie nabíjačky môže vrátiť spoločné 500 PlainError, ak zlyhá bez konkrétnejšej chybovej odpovede.

Chyby výkazov

Koncové body	Stav	Presné telo
Rozsah údajov/exportu, kde `from >= to`	`422`	`{ "validationErrors": { "range": ["from must be earlier than to"] } }`
Rozsah údajov/exportu presahuje 90 dní	`422`	`{ "validationErrors": { "range": ["Report ranges cannot exceed 90 days"] } }`
Neplatný nepriehľadný kurzor údajov/meraní	`422`	`{ "validationErrors": { "cursor": ["<message>"] } }`
`GET /reports/export`, výsledok presahuje 2 000 riadkov	`422`	`{ "error": "<message>", "code": "REPORT_EXPORT_ROW_LIMIT", "limit": 2000 }`
`POST /reports/send`, žiadny uložený harmonogram	`409`	`{ "error": "A workspace report schedule must be saved before sending", "code": "REPORT_SCHEDULE_REQUIRED" }`
To isté, poštový systém odmietne alebo zlyhá	`502`	`{ "error": "Report delivery failed", "code": "REPORT_DELIVERY_FAILED" }`
Chýba vlastnený zdroj harmonogramu/meraní	`404`	spoločné telo `RESOURCE_NOT_FOUND`

Úspešný export je binárny; všetky chyby exportu zostávajú v JSON.

Chyby taríf

Koncové body	Stav	Presné telo
Validácia doménových pravidiel vytvorenia/aktualizácie/komponentov/trhovej ceny/priradenia	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`
Konflikt odstránenia tarify alebo stavu/závislostí/jedinečnosti priradenia	`409`	`{ "error": "<message>", "code": "TARIFF_CONFLICT" }`
Chýbajúca vlastnená tarifa, obchodná zóna, nabíjačka, konektor, priradenie tarify alebo iný vnorený zdroj	`404`	spoločné telo `RESOURCE_NOT_FOUND`

Chyby nabíjacích profilov

Koncové body	Stav	Presné telo
Validácia doménových pravidiel vytvorenia/aktualizácie/harmonogramu/priradenia	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`
Na profil odkazuje chránené použitie	`409`	`{ "error": "<message>", "code": "CHARGING_PROFILE_IN_USE" }`
Konflikt synchronizácie OCPP, priradenia, súbežnosti alebo iný konflikt profilu	`409`	`{ "error": "<message>", "code": "CHARGING_PROFILE_CONFLICT" }`
Chýbajúci vlastnený profil, nabíjačka, konektor, priradenie alebo iný vnorený zdroj	`404`	spoločné telo `RESOURCE_NOT_FOUND`

Chyby používateľskej domény

Validačné chyby používateľa určujúce pole používajú ValidationError a code; ostatné používateľské chyby používajú CodedError. Všetky prípady chýbajúcich zdrojov používajú spoločnú odpoveď RESOURCE_NOT_FOUND, ktorá neodhaľuje existenciu zdrojov.

Stav	Kód(y)	Telo
`400`	`INVALID_USER_CURSOR`	`{ "validationErrors": { "cursor": ["The user-list cursor is invalid for the selected status"] }, "code": "INVALID_USER_CURSOR" }`
`409`	`USER_ALREADY_EXISTS`, `CUSTOMER_CONTRACT_MISSING`, `INVITATION_EMAIL_IN_USE`, `RFID_ALREADY_EXISTS`, `ACCESS_ALREADY_EXISTS`, `ACCESS_ALL_ALREADY_EXISTS`, `LIMIT_ALREADY_EXISTS`, `LOCAL_USER_ALREADY_EXISTS`, `PROTECTED_WORKSPACE_USER`, `TAGLESS_USER_PROTECTED`, `USER_RELATED_DATA`	`{ "error": "<message>", "code": "<listed code>" }`
`422`	`INVALID_EMAIL`, `INVALID_RFID`, `INVALID_LIMIT_TYPE`, `INVALID_LIMIT_VALUE`	`{ "validationErrors": { "<field>": ["<message>"] }, "code": "<listed code>" }`
`422`	`NO_CHARGERS_AVAILABLE`	`{ "error": "No chargers are available", "code": "NO_CHARGERS_AVAILABLE" }`
`429`	`INVITATION_RESEND_THROTTLED`	`{ "error": "Invitation resend is temporarily unavailable", "code": "INVITATION_RESEND_THROTTLED" }`; obsahuje `Retry-After`
`503`	`USER_CURSOR_UNAVAILABLE`	`{ "error": "User pagination is temporarily unavailable", "code": "USER_CURSOR_UNAVAILABLE" }`
`404`	`RESOURCE_NOT_FOUND`	`{ "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }`

POST /users/invitations môže po parsovaní tela vrátiť aj spoločné 403 INSUFFICIENT_SCOPE, ak chýba users:access alebo ak bolo zadané RFID a chýba users:rfid. Koncové body lokálnych používateľov uvádzajú všetky požadované rozsahy v časti Referenčný prehľad koncových bodov.

Používateľské chybové kódy sa uplatňujú takto:

Skupina koncových bodov	Kódy používateľskej domény iné než 404 navyše k spoločným odpovediam
`GET /users`	`INVALID_USER_CURSOR` (`400`), `USER_CURSOR_UNAVAILABLE` (`503`)
`POST /users`	`USER_ALREADY_EXISTS`, `TAGLESS_USER_PROTECTED` (`409`)
`PATCH /users/:userId`	`TAGLESS_USER_PROTECTED` (`409`)
`DELETE /users/:userId`	`TAGLESS_USER_PROTECTED`, `PROTECTED_WORKSPACE_USER`, `USER_RELATED_DATA` (`409`)
Podrobnosti používateľa, vozidlá a čítanie RFID/prístupu/limitov	žiadny doménový kód iný než 404
Vytvorenie RFID	`CUSTOMER_CONTRACT_MISSING`, `RFID_ALREADY_EXISTS`, `TAGLESS_USER_PROTECTED` (`409`); `INVALID_RFID` (`422`)
Aktualizácia/odstránenie RFID	`TAGLESS_USER_PROTECTED` (`409`)
Nahradenie prístupu	`TAGLESS_USER_PROTECTED` (`409`); `NO_CHARGERS_AVAILABLE` (`422`)
Odvolanie prístupu	`TAGLESS_USER_PROTECTED` (`409`)
Vytvorenie/aktualizácia limitu	`TAGLESS_USER_PROTECTED`, `LIMIT_ALREADY_EXISTS` (`409`); `INVALID_LIMIT_TYPE`, `INVALID_LIMIT_VALUE` (`422`)
Odstránenie limitu	`TAGLESS_USER_PROTECTED` (`409`)
Vytvorenie pozvánky pracovného priestoru	`CUSTOMER_CONTRACT_MISSING`, `INVITATION_EMAIL_IN_USE`, `RFID_ALREADY_EXISTS`, `TAGLESS_USER_PROTECTED` (`409`); `INVALID_EMAIL`/`INVALID_RFID` (`422`); `INVITATION_RESEND_THROTTLED` (`429`), keď platí odstup doručovania
Opätovné odoslanie pozvánky pracovného priestoru	`INVALID_EMAIL` (`422`), `INVITATION_RESEND_THROTTLED` (`429`)
Zrušenie pozvánky pracovného priestoru	`INVALID_EMAIL` (`422`)
Vytvorenie lokálneho používateľa nabíjačky pre existujúceho zákazníka	`LOCAL_USER_ALREADY_EXISTS`, `TAGLESS_USER_PROTECTED` (`409`)
Pozvánka lokálneho používateľa nabíjačky	`LOCAL_USER_ALREADY_EXISTS`, `INVITATION_EMAIL_IN_USE`, `TAGLESS_USER_PROTECTED` (`409`); `INVALID_EMAIL` (`422`); `INVITATION_RESEND_THROTTLED` (`429`), keď platí odstup doručovania
Zrušenie pozvánky lokálneho používateľa	`INVALID_EMAIL` (`422`)
Aktualizácia/odstránenie lokálneho používateľa	`TAGLESS_USER_PROTECTED` (`409`)

Všetky výsledky týkajúce sa vlastníctva a chýbajúcich zdrojov v týchto skupinách vrátane neregistrovaného e-mailu na POST /users používajú spoločné telo 404 RESOURCE_NOT_FOUND.

Odpovede bez tela a odpovede na opakovania

Úspešná odpoveď 204 nemá telo. Platí to pre každé zdokumentované odstránenie s uvedeným 204 empty. Dokončené idempotentné opakovanie nastaví Idempotency-Replayed: true a použije uložený stav a telo; pri 204 zostáva HTTP odpoveď bez tela. API nikdy nevracia objekt JSON potvrdzujúci úspech pre zdokumentovanú operáciu 204.