Admin API response and error contract

This file completes the response contract for every endpoint in Endpoint reference. Read the endpoint row for its success body and the tables below for every shared or endpoint-specific non-success body. By default, errors use several compatibility shapes; callers can opt into one universal envelope.

Optional structured error envelope

Send this request header on any endpoint:

X-Error-Format: envelope

The value comparison is trimmed and case-insensitive. With that exact value, every JSON response whose status is 400 or higher is converted to:

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

Example conversion of a default validation body:

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

Conversion rules are exact:

• validationErrors becomes details.fields, and code becomes VALIDATION_FAILED even when the default body also had a domain code.
• A default top-level code is retained when there are no validation fields.
• Other top-level properties except error, message, validationErrors, and code move into details; for example report export limit becomes details.limit.
• A string top-level error becomes message. If none exists, the status fallback is used.
• Fallback codes are AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 and other unclassified 4xx), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502), and INTERNAL_ERROR (other 5xx, including 503).
• requestId is the exact X-Request-Id response header. A caller-supplied request ID is used only when it matches [A-Za-z0-9._:-]{1,128} after trimming; otherwise the server generates a UUID.

This transformation does not change the status or non-body headers. It also applies to idempotent replays according to the replay request's X-Error-Format header. Binary success responses remain binary; their JSON errors are enveloped. The remaining tables show the default bodies; applying the rules above gives the other possible response body for every row.

Response notation

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

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

PlainError = { error: string }

error and validation-message text is descriptive, not a stable programmatic discriminator. Branch on code when present. Request validation returns 422 ValidationError; validation of a whole object can produce { "validationErrors": {} } when no individual field is identified. Invalid JSON and unexpected failures return the global 500 PlainError shown below.

All JSON examples are exact body shapes. Text shown as <message> is the returned validation or operation message and is a JSON string, not a literal angle-bracket value.

Request processing order

Requests are processed in this order:

1. workspace-token configuration and authentication;
2. host policy and token/workspace rate limits;
3. current entitlement filtering;
4. for every mutation, idempotency validation/claim;
5. endpoint scope checks, request validation, and the requested operation.

Consequently, a mutation with a valid but under-scoped token is still required to send Idempotency-Key. A completed 403, 404, 409, or 422 mutation response is replayable for the same key/request.

Authentication, policy, and rate-limit responses

These responses can occur on every registered /v2/admin endpoint before endpoint-specific processing.

Losing apiAccess removes all effective scopes; losing a feature entitlement removes the affected scopes. The resulting endpoint response is the scope response below, not a token refresh flow.

Scope, idempotency, parsing, ownership, and unexpected failures

Resource path IDs must be positive numbers. A non-positive or non-numeric :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId, or :localUserId returns 422 ValidationError, not 400.

Site and power-management errors

Charger errors

mapChargerErrors() is used by charger creation/update, credentials, connector settings, public listing, QR payload resolution, configuration mutation/reload, firmware start, all four basic commands, and composite-schedule request.

Plain read operations return only the shared 401/403/404/429/500/503 responses plus 422 query/path validation. Charger deletion can return the shared 500 PlainError if deletion fails without a more specific error response.

Report errors

The successful export is binary; all export errors remain JSON.

Tariff errors

Charging-profile errors

User-domain errors

User validation errors that identify a field use ValidationError plus code; other user errors use CodedError. All missing-resource cases use the shared non-enumerating RESOURCE_NOT_FOUND response.

POST /users/invitations can also return the shared 403 INSUFFICIENT_SCOPE after body parsing if users:access is missing, or if an RFID was supplied and users:rfid is missing. Local-user endpoints list every required scope in Endpoint reference.

The user error codes apply as follows:

All ownership and missing-resource outcomes in those families, including an unregistered email on POST /users, use the shared 404 RESOURCE_NOT_FOUND body.

No-body and replay responses

A successful 204 response has no body. This applies to every documented delete that lists 204 empty. A completed idempotent replay sets Idempotency-Replayed: true and uses the stored status/body; for 204, the HTTP response remains bodyless. The API never returns a JSON success object for a documented 204 operation.