Antwort- und Fehlervertrag der Admin-API

Diese Datei vervollständigt den Antwortvertrag jedes Endpunkts unter Endpunktreferenz. Die Endpunktzeile beschreibt den Erfolgs-Body, die folgenden Tabellen alle gemeinsamen und spezifischen Fehler-Bodys. Standardmäßig gibt es mehrere kompatible Fehlerformen; Aufrufer können einen einheitlichen Umschlag wählen.

Optionaler strukturierter Fehlerumschlag

Senden Sie diesen Anfrageheader an einen beliebigen Endpunkt:

X-Error-Format: envelope

Der Vergleich wird getrimmt und ignoriert Groß-/Kleinschreibung. Bei genau diesem Wert wird jede JSON-Antwort mit Status ab 400 umgewandelt in:

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

Beispiel für die Umwandlung eines Standard-Validierungs-Bodys:

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

Die Umrechnungsregeln sind exakt:

• validationErrors wird zu details.fields und code zu VALIDATION_FAILED, auch wenn der Standard-Body einen fachlichen Code hatte.
• Ein standardmäßiges code auf oberster Ebene bleibt erhalten, wenn keine Validierungsfelder vorhanden sind.
• Andere Eigenschaften oberster Ebene außer error, message, validationErrors und code werden nach details verschoben; beim Berichtsexport wird beispielsweise limit zu details.limit.
• Ein error als Zeichenfolge auf oberster Ebene wird zu message. Fehlt es, wird der Ersatztext des Status verwendet.
• Ersatzcodes sind AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 und andere nicht klassifizierte 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) und INTERNAL_ERROR (andere 5xx, einschließlich 503).
• requestId ist der exakte Antwortheader X-Request-Id. Eine vom Aufrufer angegebene Anfrage-ID gilt nur, wenn sie nach Trimmen [A-Za-z0-9._:-]{1,128} entspricht; sonst erzeugt der Server eine UUID.

Die Umwandlung verändert weder Status noch andere Header. Sie gilt auch für idempotente Wiederholungen gemäß deren X-Error-Format-Anfrageheader. Binäre Erfolge bleiben binär, ihre JSON-Fehler erhalten den Umschlag. Die übrigen Tabellen zeigen Standard-Bodys; die Regeln oben ergeben für jede Zeile die andere mögliche Antwortform.

Schreibweise von Antworten

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

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

PlainError = { error: string }

error und der Validierungsmeldungstext dienen der Beschreibung, nicht als stabile programmatische Unterscheidungsmerkmale. Verzweigen Sie nach code, falls vorhanden. Anfragevalidierung liefert 422 ValidationError; Objektvalidierung kann ohne bestimmtes Feld { "validationErrors": {} } erzeugen. Ungültiges JSON und unerwartete Fehler liefern das globale 500 PlainError unten.

Alle JSON-Beispiele zeigen die exakte Body-Struktur. Als <message> angezeigter Text ist die zurückgegebene Validierungs- oder Vorgangsmeldung und eine JSON-Zeichenfolge, kein wörtlicher Wert in spitzen Klammern.

Reihenfolge der Anfrageverarbeitung

Anfragen werden in dieser Reihenfolge verarbeitet:

1. Workspace-Token-Konfiguration und Authentifizierung;
2. Host-Richtlinie und Token-/Workspace-Anfragelimits;
3. Filterung aktueller Funktionsberechtigungen;
4. bei jeder Änderung Idempotenzprüfung/-reservierung;
5. Endpunkt-Scope-Prüfungen, Anfragevalidierung und angeforderter Vorgang.

Daher muss auch eine Änderung mit gültigem, aber unzureichend berechtigtem Token Idempotency-Key senden. Eine abgeschlossene Änderungsantwort mit 403, 404, 409 oder 422 kann für denselben Schlüssel und dieselbe Anfrage wiederholt werden.

Antworten zu Authentifizierung, Richtlinien und Anfragelimits

Diese Antworten können an jedem registrierten /v2/admin-Endpunkt vor der endpunktspezifischen Verarbeitung auftreten.

API-Zugriff ist in jedem Paket enthalten. Wird die Host-Einstellung adminApiEnabled deaktiviert, liefert der Workspace 404; entfällt eine zusätzliche Funktionsberechtigung, werden nur die betroffenen Scopes entfernt. Die daraus folgende Scope-Verweigerung verwendet die folgende Antwort und keinen Token-Aktualisierungsablauf.

Fehler bei Scope, Idempotenz, Parsing, Besitzrechten und unerwarteten Zuständen

Ressourcenpfad-IDs müssen positiv sein. Ein nicht positives oder nicht numerisches :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId oder :localUserId liefert 422 ValidationError, nicht 400.

Standort- und Leistungsmanagement-Fehler

Ladegerätefehler

mapChargerErrors() wird für Geräteerstellung/-änderung, Zugangsdaten, Anschlüsse, öffentliche Listung, QR-Auflösung, Konfigurationsänderung/-neuladen, Firmwarestart, alle vier Basisbefehle und kombinierte Zeitplananfragen verwendet.

Reine Lesevorgänge liefern nur gemeinsame 401/403/404/429/500/503-Antworten sowie 422-Validierung für Query und Pfad. Die Gerätelöschung kann das gemeinsame 500 PlainError liefern, falls sie ohne spezifischere Fehlerantwort scheitert.

Berichtsfehler

Ein erfolgreicher Export ist binär; alle Exportfehler bleiben JSON.

Tariffehler

Ladeprofilfehler

Fachliche Benutzerfehler

Benutzer-Validierungsfehler mit Feldbezug verwenden ValidationError und code; andere Benutzerfehler CodedError. Fehlende Ressourcen verwenden immer die gemeinsame nicht auskunftgebende RESOURCE_NOT_FOUND-Antwort.

POST /users/invitations kann nach dem Body-Parsing auch das gemeinsame 403 INSUFFICIENT_SCOPE liefern, wenn users:access fehlt oder bei übergebenem RFID users:rfid fehlt. Lokale Benutzerendpunkte nennen alle erforderlichen Scopes unter Endpunktreferenz.

Die Benutzerfehlercodes gelten wie folgt:

Alle Ergebnisse zu Besitzrechten oder fehlenden Ressourcen in diesen Gruppen, auch eine nicht registrierte E-Mail bei POST /users, verwenden den gemeinsamen Body 404 RESOURCE_NOT_FOUND.

Antworten ohne Body und Wiederholungsantworten

Eine erfolgreiche 204-Antwort hat keinen Antwortinhalt. Dies gilt für alle dokumentierten Löschvorgänge, die 204 empty aufführen. Eine abgeschlossene idempotente Wiederholung setzt Idempotency-Replayed: true und verwendet den gespeicherten Status und Inhalt; bei 204 bleibt die HTTP-Antwort ohne Inhalt. Bei einem dokumentierten 204-Vorgang liefert die API niemals ein JSON-Erfolgsobjekt.