Contratto di risposte ed errori dell’API di amministrazione

Questo file completa il contratto delle risposte per ogni endpoint in Riferimento degli endpoint. Leggi la riga dell'endpoint per il corpo di successo e le tabelle seguenti per tutti i corpi di errore comuni o specifici dell'endpoint. Per impostazione predefinita, gli errori usano diverse strutture di compatibilità; i chiamanti possono scegliere un'unica struttura universale.

Struttura di errore facoltativa

Invia questa intestazione di richiesta a qualsiasi endpoint:

X-Error-Format: envelope

Il confronto del valore ignora gli spazi iniziali e finali e non distingue tra maiuscole e minuscole. Con quel valore esatto, ogni risposta JSON con stato pari o superiore a 400 viene convertita in:

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

Esempio di conversione di un corpo di validazione predefinito:

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

Le regole di conversione sono esatte:

• validationErrors diventa details.fields e code diventa VALIDATION_FAILED, anche quando il corpo predefinito conteneva già un codice di dominio.
• Il valore code predefinito al livello principale viene mantenuto quando non sono presenti campi di validazione.
• Le altre proprietà di primo livello, escluse error, message, validationErrors e code, vengono spostate in details; ad esempio, l'esportazione dei report limit diventa details.limit.
• Un campo error di tipo stringa al livello principale diventa message. Se non esiste, viene usato il messaggio predefinito per lo stato.
• I codici di ripiego sono AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 e altri 4xx non classificati), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) e INTERNAL_ERROR (altri 5xx, incluso 503).
• requestId è l'esatta intestazione di risposta X-Request-Id. Un ID di richiesta fornito dal chiamante viene usato solo se, dopo la rimozione degli spazi iniziali e finali, corrisponde a [A-Za-z0-9._:-]{1,128}; altrimenti il server genera un UUID.

Questa trasformazione non modifica lo stato né le intestazioni non relative al corpo. Si applica anche alle riproduzioni idempotenti in base all'intestazione X-Error-Format della richiesta di riproduzione. Le risposte binarie di successo rimangono binarie; i loro errori JSON vengono racchiusi nella struttura. Le tabelle rimanenti mostrano i corpi predefiniti; applicando le regole precedenti si ottiene l'altro possibile corpo di risposta per ogni riga.

Notazione delle risposte

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

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

PlainError = { error: string }

error e il testo dei messaggi di convalida sono descrittivi, non discriminatori programmatici stabili. Basa le diramazioni su code, se presente. La convalida delle richieste restituisce 422 ValidationError; la convalida di un intero oggetto può produrre { "validationErrors": {} } quando non viene identificato un singolo campo. JSON non valido ed errori imprevisti restituiscono il 500 PlainError globale mostrato di seguito.

Tutti gli esempi JSON mostrano le strutture esatte del corpo. Il testo rappresentato da <message> è il messaggio di validazione o dell’operazione restituito ed è una stringa JSON, non un valore letterale tra parentesi angolari.

Ordine di elaborazione delle richieste

Le richieste vengono elaborate in questo ordine:

1. configurazione e autenticazione dei token dello spazio di lavoro;
2. criteri dell'host e limiti di frequenza del token/spazio di lavoro;
3. filtro delle abilitazioni correnti;
4. per ogni operazione di modifica, convalida/acquisizione dell'idempotenza;
5. controlli degli ambiti dell'endpoint, convalida della richiesta e operazione richiesta.

Di conseguenza, anche una mutazione con un token valido ma con ambiti insufficienti deve inviare Idempotency-Key. Una risposta completata a una mutazione 403, 404, 409 o 422 può essere ripetuta per la stessa chiave e richiesta.

Risposte di autenticazione, criteri e limitazione delle richieste

Queste risposte possono verificarsi su ogni endpoint /v2/admin registrato prima dell'elaborazione specifica dell'endpoint.

L’accesso API è incluso in ogni piano. Disabilitare l’impostazione adminApiEnabled dell’host dello spazio di lavoro restituisce 404; perdere un diritto aggiuntivo a una funzione rimuove solo gli ambiti interessati. Il conseguente rifiuto dell’ambito usa la risposta seguente, non una procedura di aggiornamento del token.

Errori relativi ad ambiti, idempotenza, analisi, proprietà ed errori imprevisti

Gli ID delle risorse nel percorso devono essere numeri positivi. Un valore :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId o :localUserId non positivo o non numerico restituisce 422 ValidationError, non 400.

Errori dei siti e della gestione della potenza

Errori dei caricatori

mapChargerErrors() viene usato per creazione/aggiornamento dei caricatori, credenziali, impostazioni dei connettori, pubblicazione nell'elenco pubblico, risoluzione dei dati del codice QR, modifica/ricaricamento della configurazione, avvio del firmware, tutti e quattro i comandi di base e richiesta della pianificazione composita.

Le semplici operazioni di lettura restituiscono solo le risposte comuni 401/403/404/429/500/503 e 422 per la convalida della query o del percorso. L'eliminazione di un caricatore può restituire la risposta comune 500 PlainError se non riesce senza una risposta di errore più specifica.

Errori dei report

L'esportazione riuscita è binaria; tutti gli errori di esportazione rimangono JSON.

Errori delle tariffe

Errori dei profili di ricarica

Errori del dominio utenti

Gli errori di convalida degli utenti che identificano un campo usano ValidationError insieme a code; gli altri errori degli utenti usano CodedError. Tutti i casi di risorse mancanti usano la risposta comune RESOURCE_NOT_FOUND, che non consente l'enumerazione delle risorse.

POST /users/invitations può anche restituire la risposta comune 403 INSUFFICIENT_SCOPE dopo l'analisi del corpo se manca users:access, oppure se è stato fornito un RFID e manca users:rfid. Gli endpoint degli utenti locali elencano tutti gli ambiti richiesti in Riferimento degli endpoint.

I codici di errore degli utenti si applicano come segue:

Tutti gli esiti relativi a proprietà e risorse mancanti in queste famiglie, inclusa un’e-mail non registrata su POST /users, usano il corpo comune 404 RESOURCE_NOT_FOUND.

Risposte senza corpo e risposte riprodotte

Una risposta 204 riuscita non ha corpo. Questo vale per ogni eliminazione documentata che indica 204 empty. Una ripetizione idempotente completata imposta Idempotency-Replayed: true e usa lo stato e il corpo salvati; per 204, la risposta HTTP rimane senza corpo. L’API non restituisce mai un oggetto JSON di successo per un’operazione 204 documentata.