Ugovor odgovora i pogrešaka administratorskog API-ja

Ova datoteka dopunjuje ugovor odgovora za svaku krajnju točku iz Referentnog pregleda krajnjih točaka. U retku krajnje točke pročitajte tijelo uspješnog odgovora, a u tablicama ispod sva zajednička tijela neuspješnih odgovora i ona specifična za krajnju točku. Pogreške zadano upotrebljavaju više oblika radi kompatibilnosti; pozivatelji mogu odabrati jednu univerzalnu omotnicu.

Neobavezna strukturirana omotnica pogreške

Pošaljite ovo zaglavlje zahtjeva na bilo kojoj krajnjoj točki:

X-Error-Format: envelope

Pri usporedbi vrijednosti uklanjaju se rubni razmaci i ne razlikuju se velika i mala slova. Uz tu točnu vrijednost svaki JSON odgovor sa statusom 400 ili višim pretvara se u:

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

Primjer pretvorbe zadanog tijela validacije:

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

Pravila pretvorbe su točna:

validationErrors postaje details.fields, a code postaje VALIDATION_FAILED čak i kada je zadano tijelo sadržavalo i domenski kod.
Zadana vrijednost code na najvišoj razini zadržava se kada nema polja za validaciju.
Ostala svojstva na najvišoj razini, osim error, message, validationErrors i code, premještaju se u details; primjerice, limit iz izvoza izvještaja postaje details.limit.
Vrijednost error na najvišoj razini, ako je tekstualni niz, postaje message. Ako ne postoji, upotrebljava se zadana poruka za status.
Zadani kodovi su AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 i drugi nerazvrstani 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) i INTERNAL_ERROR (drugi 5xx, uključujući 503).
requestId točno je zaglavlje odgovora X-Request-Id. ID zahtjeva koji zada pozivatelj upotrebljava se samo ako nakon uklanjanja rubnih razmaka odgovara [A-Za-z0-9._:-]{1,128}; u suprotnom poslužitelj generira UUID.

Ova pretvorba ne mijenja status ni zaglavlja koja nisu povezana s tijelom. Primjenjuje se i na idempotentna ponavljanja prema zaglavlju X-Error-Format zahtjeva za ponavljanje. Binarni uspješni odgovori ostaju binarni; njihove se JSON pogreške omotavaju. Preostale tablice prikazuju zadana tijela; primjenom prethodnih pravila dobiva se drugo moguće tijelo odgovora za svaki redak.

Oznake odgovora

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

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

PlainError = { error: string }

error i tekst poruke validacije opisni su, a nisu stabilni kriteriji za programsko razlikovanje. Odluke temeljite na code kada je prisutan. Validacija zahtjeva vraća 422 ValidationError; validacija cijelog objekta može proizvesti { "validationErrors": {} } kada nije određeno pojedinačno polje. Nevaljani JSON i neočekivani kvarovi vraćaju globalni 500 PlainError prikazan u nastavku.

Svi JSON primjeri prikazuju točan oblik tijela. Tekst prikazan kao <message> vraćena je poruka validacije ili operacije i predstavlja JSON tekstualni niz, a ne doslovnu vrijednost s kutnim zagradama.

Redoslijed obrade zahtjeva

Zahtjevi se obrađuju ovim redoslijedom:

konfiguracija i autentifikacija tokena radnog prostora;
pravila pružatelja usluge i ograničenja učestalosti za token/radni prostor;
filtriranje prema trenutačnim pravima;
za svaku operaciju koja mijenja podatke, provjera i rezervacija ključa idempotentnosti;
provjere opsega pristupa krajnje točke, validacija zahtjeva i zatražena operacija.

Stoga i zahtjev koji mijenja podatke s valjanim tokenom, ali nedostatnim opsegom pristupa, mora poslati Idempotency-Key. Dovršeni odgovor na operaciju 403, 404, 409 ili 422 može se ponovno dobiti za isti ključ i zahtjev.

Odgovori autentifikacije, pravila pristupa i ograničenja učestalosti zahtjeva

Ovi se odgovori mogu pojaviti na svakoj registriranoj krajnjoj točki /v2/admin prije obrade specifične za krajnju točku.

Status	Kada	Točno tijelo	Relevantna zaglavlja
`401`	Nedostajući, duplicirani, zarezom spojeni token radnog prostora, token bez sheme Bearer, neispravno oblikovan, nepoznat, istekao, opozvan ili na drugi način nevaljan token	`{ "error": "Unauthorized", "code": "INVALID_WORKSPACE_TOKEN" }`	`WWW-Authenticate: Bearer`, `Cache-Control: no-store`
`404`	Token je valjan, ali pružatelj usluge njegova radnog prostora nema `adminApiEnabled`	`{ "error": "Not Found" }`	`Cache-Control: no-store`
`429`	Iscrpljeno ograničenje zahtjeva po tokenu ili radnom prostoru	`{ "error": "Too many attempts. Please try again later." }`	`Retry-After: <seconds>`
`503`	Autentifikacija tokena radnog prostora privremeno nije dostupna	`{ "error": "Admin API workspace-token configuration is unavailable", "code": "WORKSPACE_API_CONFIG_UNAVAILABLE" }`	—
`503`	Neuspješno dohvaćanje pravila pružatelja usluge ili autorizacija trenutačnih prava	`{ "error": "Workspace authorization is temporarily unavailable", "code": "WORKSPACE_AUTHORIZATION_UNAVAILABLE" }`	—

Pristup API-ju uključen je u sve pakete. Isključivanje postavke adminApiEnabled kod pružatelja radnog prostora vraća 404; gubitak dodatnog prava na značajku uklanja samo zahvaćene opsege pristupa. Za takvo odbijanje opsega upotrebljava se odgovor u nastavku, a ne postupak osvježavanja tokena.

Pogreške opsega pristupa, idempotentnosti, parsiranja, vlasništva i neočekivani kvarovi

Primjenjuje se na	Status	Točno tijelo	Zaglavlja/napomene
Svaka ruta nakon autentifikacije	`403`	`{ "error": "Insufficient workspace-token scope", "code": "INSUFFICIENT_SCOPE" }`	Vraća se kada nedostaje bilo koji obavezan opseg pristupa.
Svaka operacija koja mijenja podatke	`400`	`{ "error": "Idempotency-Key is required for this operation", "code": "IDEMPOTENCY_KEY_REQUIRED" }`	Ključ nije poslan.
Svaka operacija koja mijenja podatke	`400`	`{ "error": "Exactly one Idempotency-Key is required", "code": "INVALID_IDEMPOTENCY_KEY" }`	Duplicirano zaglavlje ili vrijednosti zaglavlja spojene zarezom.
Svaka operacija koja mijenja podatke	`400`	`{ "error": "Idempotency-Key must contain 1 to 255 visible characters", "code": "INVALID_IDEMPOTENCY_KEY" }`	Prazno, predugo ili sadrži kontrolni znak.
Svaka operacija koja mijenja podatke	`409`	`{ "error": "Idempotency-Key was already used with a different request", "code": "IDEMPOTENCY_CONFLICT" }`	Isti token/metoda/putanja/ključ, ali drukčiji URL ili tijelo.
Svaka operacija koja mijenja podatke	`409`	`{ "error": "Request is already processing", "code": "IDEMPOTENT_REQUEST_PROCESSING" }`	`Retry-After: 5`.
Svaka operacija koja mijenja podatke	`409`	`{ "error": "Previous request outcome is unknown; verify its effects before attempting the operation again", "code": "IDEMPOTENCY_OUTCOME_UNKNOWN" }`	Prethodna vremenska rezervacija za obradu je istekla, veza je zatvorena ili je zahtjev završio s `5xx`.
Svaka operacija koja mijenja podatke	`503`	`{ "error": "Idempotency storage unavailable", "code": "IDEMPOTENCY_UNAVAILABLE" }`	API ne može provjeriti ili spremiti zapis idempotentnosti.
Bilo koja krajnja točka s nevaljanom shemom upita, tijela ili putanje	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`	Može biti prisutno više polja ili poruka. Pozivatelji ne mogu zadati `cpoId`; radni prostor uvijek se određuje iz tokena.
Bilo koji slučaj nedostajućeg ugniježđenog resursa radnog prostora ili ID iz drugog radnog prostora	`404`	`{ "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }`	Primjenjuje se dosljedno, osim ako u tablici u nastavku nije navedeno drukčije.
Bilo koja krajnja točka s neočekivanim kvarom	`500`	`{ "error": "Something went wrong" }`	Za operacije koje mijenjaju podatke kasniji ponovni pokušaj s istim ključem vraća `409 IDEMPOTENCY_OUTCOME_UNKNOWN`.

ID-jevi resursa u putanji moraju biti pozitivni brojevi. Nepozitivni ili nebrojčani :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId ili :localUserId vraća 422 ValidationError, a ne 400.

Pogreške lokacija i upravljanja snagom

Krajnje točke	Status	Točno tijelo
Stvaranje/ažuriranje lokacije; validacija polja radnog prostora	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`
`DELETE /v2/admin/sites/:siteId` kada lokacija ima ovisnosti	`409`	`{ "error": "<message>", "code": "SITE_NOT_EMPTY" }`
`GET /v2/admin/sites/geocode` nevaljano normalizirano pretraživanje	`400`	`{ "error": "<message>", "code": "INVALID_GEOCODE_QUERY" }`
Isto, popunjen ograničeni red pružatelja usluge	`429`	`{ "error": "<message>", "code": "GEOCODING_BUSY" }`; uključuje `Retry-After` kada ga dostavi usluga geokodiranja
Isto, istek vremena ili kvar pružatelja usluge ili neočekivana pogreška geokodiranja	`502`	`{ "error": "<message>", "code": "GEOCODING_UNAVAILABLE" }`; neočekivana pogreška upotrebljava `Address search is temporarily unavailable`
`PUT /v2/admin/sites/:siteId/power-management` nevaljana topologija ili domenska konfiguracija	`422`	`{ "error": "<message>", "code": "INVALID_POWER_MANAGEMENT_CONFIGURATION" }`
Isto, OCPP odbijanje/istek vremena, utrka istodobnih operacija ili sukob usklađivanja	`409`	`{ "error": "<message>", "code": "POWER_MANAGEMENT_CONFLICT" }`

Pogreške punjača

mapChargerErrors() upotrebljavaju stvaranje/ažuriranje punjača, vjerodajnice, postavke priključka, javna objava, razrješavanje QR podataka, izmjena/ponovno učitavanje konfiguracije, pokretanje firmvera, sve četiri osnovne naredbe i zahtjev za objedinjeni raspored.

Krajnje točke	Status	Točno tijelo
Bilo koja prethodno navedena operacija s pogreškom validacije domenskih pravila	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`
Bilo koja prethodno navedena operacija sa sukobom vezanim uz stanje, jedinstvenost, izvanmrežni rad/OCPP, naplatu, način bez identifikacijske oznake, priključak ili spremnost	`409`	`{ "error": "<message>", "code": "CHARGER_CONFLICT" }`
`GET /chargers/:chargerId/sessions`, nevaljan zadani ili izričito naveden vremenski raspon	`422`	`{ "validationErrors": { "from": ["from must be before or equal to to"] } }` ili `{ "validationErrors": { "from": ["Session range cannot exceed 90 days"] } }`

Obične operacije čitanja vraćaju samo zajedničke odgovore 401/403/404/429/500/503 i 422 za validaciju upita ili putanje. Brisanje punjača može vratiti zajednički 500 PlainError ako brisanje ne uspije bez konkretnijeg odgovora s pogreškom.

Pogreške izvještaja

Krajnje točke	Status	Točno tijelo
Raspon podataka/izvoza u kojem je `from >= to`	`422`	`{ "validationErrors": { "range": ["from must be earlier than to"] } }`
Raspon podataka/izvoza dulji od 90 dana	`422`	`{ "validationErrors": { "range": ["Report ranges cannot exceed 90 days"] } }`
Nevaljani neprozirni pokazivač za podatke/mjerenja	`422`	`{ "validationErrors": { "cursor": ["<message>"] } }`
`GET /reports/export`, rezultat premašuje 2.000 redaka	`422`	`{ "error": "<message>", "code": "REPORT_EXPORT_ROW_LIMIT", "limit": 2000 }`
`POST /reports/send`, nema spremljenog rasporeda	`409`	`{ "error": "A workspace report schedule must be saved before sending", "code": "REPORT_SCHEDULE_REQUIRED" }`
Isto, odbijanje ili kvar sustava slanja e-pošte	`502`	`{ "error": "Report delivery failed", "code": "REPORT_DELIVERY_FAILED" }`
Nedostaje pripadajući resurs rasporeda/mjerenja	`404`	zajedničko tijelo `RESOURCE_NOT_FOUND`

Uspješan izvoz je binaran; sve pogreške izvoza ostaju u JSON formatu.

Pogreške tarifa

Krajnje točke	Status	Točno tijelo
Validacija domenskih pravila za stvaranje/ažuriranje/komponente/tržišnu cijenu/dodjelu	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`
Sukob brisanja tarife ili stanja/ovisnosti/jedinstvenosti dodjele	`409`	`{ "error": "<message>", "code": "TARIFF_CONFLICT" }`
Nije pronađena tarifa, zona trgovanja, punjač, priključak, dodjela tarife ili drugi ugniježđeni resurs koji pripada radnom prostoru	`404`	zajedničko tijelo `RESOURCE_NOT_FOUND`

Pogreške profila punjenja

Krajnje točke	Status	Točno tijelo
Validacija domenskih pravila za stvaranje/ažuriranje/raspored/dodjelu	`422`	`{ "validationErrors": { "<field>": ["<message>"] } }`
Na profil se poziva zaštićena upotreba	`409`	`{ "error": "<message>", "code": "CHARGING_PROFILE_IN_USE" }`
Sukob sinkronizacije OCPP-a, dodjele, istodobnih operacija ili drugi sukob profila	`409`	`{ "error": "<message>", "code": "CHARGING_PROFILE_CONFLICT" }`
Nije pronađen profil, punjač, priključak, dodjela ili drugi ugniježđeni resurs koji pripada radnom prostoru	`404`	zajedničko tijelo `RESOURCE_NOT_FOUND`

Pogreške korisničke domene

Pogreške validacije korisnika koje određuju polje upotrebljavaju ValidationError i code; ostale korisničke pogreške upotrebljavaju CodedError. Svi slučajevi nedostajućih resursa upotrebljavaju zajednički odgovor RESOURCE_NOT_FOUND, koji ne otkriva postojanje resursa.

Status	Kodovi	Tijelo
`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" }`; uključuje `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 može vratiti i zajednički 403 INSUFFICIENT_SCOPE nakon parsiranja tijela ako nedostaje users:access ili ako je RFID naveden, a nedostaje users:rfid. Krajnje točke za lokalne korisnike navode sve potrebne opsege pristupa u Referentnom pregledu krajnjih točaka.

Kodovi korisničkih pogrešaka primjenjuju se ovako:

Skupina krajnjih točaka	Kodovi korisničke domene koji nisu 404, uz zajedničke odgovore
`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`)
Pojedinosti korisnika, vozila i čitanje RFID-a/pristupa/ograničenja	nema domenskog koda koji nije 404
Stvaranje RFID-a	`CUSTOMER_CONTRACT_MISSING`, `RFID_ALREADY_EXISTS`, `TAGLESS_USER_PROTECTED` (`409`); `INVALID_RFID` (`422`)
Ažuriranje/brisanje RFID-a	`TAGLESS_USER_PROTECTED` (`409`)
Zamjena pristupa	`TAGLESS_USER_PROTECTED` (`409`); `NO_CHARGERS_AVAILABLE` (`422`)
Opoziv pristupa	`TAGLESS_USER_PROTECTED` (`409`)
Stvaranje/ažuriranje ograničenja	`TAGLESS_USER_PROTECTED`, `LIMIT_ALREADY_EXISTS` (`409`); `INVALID_LIMIT_TYPE`, `INVALID_LIMIT_VALUE` (`422`)
Brisanje ograničenja	`TAGLESS_USER_PROTECTED` (`409`)
Stvaranje pozivnice radnog prostora	`CUSTOMER_CONTRACT_MISSING`, `INVITATION_EMAIL_IN_USE`, `RFID_ALREADY_EXISTS`, `TAGLESS_USER_PROTECTED` (`409`); `INVALID_EMAIL`/`INVALID_RFID` (`422`); `INVITATION_RESEND_THROTTLED` (`429`) kada vrijedi obavezan razmak između slanja
Ponovno slanje pozivnice radnog prostora	`INVALID_EMAIL` (`422`), `INVITATION_RESEND_THROTTLED` (`429`)
Otkazivanje pozivnice radnog prostora	`INVALID_EMAIL` (`422`)
Stvaranje lokalnog korisnika punjača za postojećeg korisnika	`LOCAL_USER_ALREADY_EXISTS`, `TAGLESS_USER_PROTECTED` (`409`)
Pozivnica lokalnom korisniku punjača	`LOCAL_USER_ALREADY_EXISTS`, `INVITATION_EMAIL_IN_USE`, `TAGLESS_USER_PROTECTED` (`409`); `INVALID_EMAIL` (`422`); `INVITATION_RESEND_THROTTLED` (`429`) kada vrijedi obavezan razmak između slanja
Otkazivanje pozivnice lokalnom korisniku	`INVALID_EMAIL` (`422`)
Ažuriranje/brisanje lokalnog korisnika	`TAGLESS_USER_PROTECTED` (`409`)

Svi ishodi povezani s vlasništvom i nedostajućim resursima u tim skupinama, uključujući neregistriranu adresu e-pošte na POST /users, upotrebljavaju zajedničko tijelo 404 RESOURCE_NOT_FOUND.

Odgovori bez tijela i odgovori na ponavljanja

Uspješan odgovor 204 nema tijelo. To vrijedi za svako dokumentirano brisanje za koje je naveden 204 empty. Dovršeno idempotentno ponavljanje postavlja Idempotency-Replayed: true i upotrebljava spremljeni status i tijelo; za 204 HTTP odgovor i dalje nema tijelo. API nikada ne vraća JSON objekt uspjeha za dokumentiranu operaciju 204.