Antwoord- en foutcontract van de beheer-API

Dit bestand vult het antwoordcontract aan voor elk eindpunt in Eindpuntreferentie. Lees de eindpuntrij voor de succesbody en de onderstaande tabellen voor elke gedeelde of eindpuntspecifieke body bij mislukking. Fouten gebruiken standaard meerdere compatibiliteitsstructuren; aanroepende toepassingen kunnen één universeel omhulsel kiezen.

Optioneel gestructureerd foutomhulsel

Stuur deze verzoekheader naar een willekeurig eindpunt:

X-Error-Format: envelope

Bij het vergelijken van waarden worden spaties aan het begin en einde genegeerd en wordt geen onderscheid gemaakt tussen hoofdletters en kleine letters. Met die exacte waarde wordt elk JSON-antwoord met status 400 of hoger omgezet naar:

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

Voorbeeld van de conversie van een standaardvalidatiebody:

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

De conversieregels zijn exact:

• validationErrors wordt details.fields en code wordt VALIDATION_FAILED, ook als de standaardbody een domeincode bevatte.
• Een standaardwaarde voor code op het hoogste niveau blijft behouden als er geen validatievelden zijn.
• Andere eigenschappen op het hoogste niveau, behalve error, message, validationErrors en code, worden naar details verplaatst; limit van een rapportexport wordt bijvoorbeeld details.limit.
• Een tekenreeks error op het hoogste niveau wordt message. Als die ontbreekt, wordt de standaardmelding voor de status gebruikt.
• De terugvalcodes zijn AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 en andere niet-geclassificeerde 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) en INTERNAL_ERROR (andere 5xx, waaronder 503).
• requestId is de exacte X-Request-Id-antwoordheader. Een door de aanroeper opgegeven verzoek-ID wordt alleen gebruikt als deze na het verwijderen van spaties aan het begin en einde voldoet aan [A-Za-z0-9._:-]{1,128}; anders genereert de server een UUID.

Deze omzetting verandert de status of headers die niet op de body betrekking hebben niet. Ze geldt ook voor idempotente herhalingen op basis van de X-Error-Format-header van het herhalingsverzoek. Binaire succesantwoorden blijven binair; hun JSON-fouten worden in een omhulsel geplaatst. De overige tabellen tonen de standaardbodies; toepassing van bovenstaande regels geeft voor elke rij de andere mogelijke antwoordbody.

Antwoordnotatie

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

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

PlainError = { error: string }

error en de tekst van validatieberichten zijn beschrijvend en geen stabiele programmatische onderscheidingscriteria. Baseer beslissingen op code wanneer die aanwezig is. Verzoekvalidatie retourneert 422 ValidationError; validatie van een volledig object kan { "validationErrors": {} } opleveren als geen afzonderlijk veld wordt aangewezen. Ongeldige JSON en onverwachte fouten retourneren de hieronder getoonde globale 500 PlainError.

Alle JSON-voorbeelden tonen de exacte bodystructuur. Tekst die als <message> wordt weergegeven, is het geretourneerde validatie- of bewerkingsbericht en is een JSON-tekenreeks, geen letterlijke waarde tussen punthaken.

Verwerkingsvolgorde van verzoeken

Verzoeken worden in deze volgorde verwerkt:

1. configuratie en authenticatie van werkruimtetokens;
2. beleid van de aanbieder en verzoeklimieten voor token/werkruimte;
3. filtering op huidige functierechten;
4. voor elke mutatie: idempotentievalidatie en claim;
5. scopecontroles van het eindpunt, verzoekvalidatie en de gevraagde bewerking.

Een mutatie met een geldig token dat onvoldoende scopes heeft, moet dus nog steeds Idempotency-Key versturen. Een voltooid 403-, 404-, 409- of 422-mutatieantwoord kan met dezelfde sleutel en hetzelfde verzoek worden herhaald.

Antwoorden voor authenticatie, beleid en verzoeklimieten

Deze antwoorden kunnen bij elk geregistreerd /v2/admin-eindpunt optreden vóór de eindpuntspecifieke verwerking.

API-toegang is inbegrepen in elk abonnement. Als de instelling adminApiEnabled van de werkruimteaanbieder wordt uitgeschakeld, volgt 404; als een aanvullend functierecht vervalt, verdwijnen alleen de bijbehorende scopes. De resulterende scopeweigering gebruikt het onderstaande antwoord, geen tokenvernieuwingsprocedure.

Fouten in scope, idempotentie, parsing, eigendom en onverwachte fouten

Resourcepad-ID's moeten positieve getallen zijn. Een niet-positieve of niet-numerieke :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId of :localUserId retourneert 422 ValidationError, niet 400.

Fouten voor locaties en vermogensbeheer

Laderfouten

mapChargerErrors() wordt gebruikt bij laderaanmaak/-update, referenties, connectorinstellingen, openbare vermelding, het oplossen van QR-inhoud, configuratiewijziging/-herlading, firmwarestart, alle vier basisopdrachten en het opvragen van een samengesteld schema.

Gewone leesbewerkingen retourneren alleen de gedeelde 401/403/404/429/500/503-antwoorden plus 422 voor query-/padvalidatie. Het verwijderen van een lader kan de gedeelde 500 PlainError retourneren als het verwijderen mislukt zonder een specifieker foutantwoord.

Rapportfouten

De geslaagde export is binair; alle exportfouten blijven JSON.

Tarieffouten

Fouten in laadprofielen

Fouten in het gebruikersdomein

Gebruikersvalidatiefouten die een veld aangeven, gebruiken ValidationError plus code; andere gebruikersfouten gebruiken CodedError. Alle gevallen van ontbrekende resources gebruiken het gedeelde RESOURCE_NOT_FOUND-antwoord dat het bestaan van resources niet onthult.

POST /users/invitations kan na het parsen van de body ook de gedeelde 403 INSUFFICIENT_SCOPE retourneren als users:access ontbreekt, of als RFID is opgegeven en users:rfid ontbreekt. Eindpunten voor lokale gebruikers vermelden elke vereiste scope in Eindpuntreferentie.

De gebruikersfoutcodes gelden als volgt:

Alle resultaten voor eigendom en ontbrekende resources in die groepen, waaronder een niet-geregistreerd e-mailadres bij POST /users, gebruiken de gedeelde 404 RESOURCE_NOT_FOUND-body.

Antwoorden zonder body en herhalingsantwoorden

Een geslaagd 204-antwoord heeft geen body. Dit geldt voor elke gedocumenteerde verwijderactie waarvoor 204 empty staat vermeld. Een voltooide idempotente herhaling stelt Idempotency-Replayed: true in en gebruikt de opgeslagen status/body; bij 204 blijft het HTTP-antwoord zonder body. De API retourneert nooit een JSON-succesobject voor een gedocumenteerde 204-bewerking.