Contrato de respuestas y errores de Admin API

Este archivo completa el contrato de respuesta de cada endpoint de la Referencia de endpoints. Consulta en la fila del endpoint el cuerpo correcto y en las tablas siguientes todos los cuerpos compartidos o específicos de respuestas no satisfactorias. Por defecto, los errores utilizan varias estructuras de compatibilidad; los clientes pueden optar por una envoltura universal.

Envoltura de error estructurada opcional

Envía esta cabecera de solicitud a cualquier endpoint:

X-Error-Format: envelope

La comparación del valor elimina espacios de los extremos y no distingue mayúsculas de minúsculas. Con ese valor exacto, toda respuesta JSON cuyo estado sea 400 o superior se convierte en:

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

Ejemplo de conversión de un cuerpo de validación predeterminado:

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

Las reglas de conversión son exactas:

• validationErrors se convierte en details.fields y code en VALIDATION_FAILED, incluso cuando el cuerpo predeterminado ya tenía un código de dominio.
• El code de nivel superior predeterminado se conserva cuando no hay campos de validación.
• Las demás propiedades de nivel superior, excepto error, message, validationErrors y code, se trasladan a details; por ejemplo, limit de la exportación de informes se convierte en details.limit.
• Un error de nivel superior de tipo cadena se convierte en message. Si no existe, se utiliza el texto de respaldo del estado.
• Los códigos de respaldo son AUTH_REQUIRED (401), PERMISSION_DENIED (403), RESOURCE_NOT_FOUND (404), CONFLICT (409), VALIDATION_FAILED (422 y otros 4xx sin clasificar), RATE_LIMITED (429), EXTERNAL_PROVIDER_FAILED (502) y INTERNAL_ERROR (otros 5xx, incluido 503).
• requestId es la cabecera de respuesta X-Request-Id exacta. Un ID de solicitud proporcionado por el cliente solo se utiliza si coincide con [A-Za-z0-9._:-]{1,128} tras eliminar los espacios de los extremos; de lo contrario, el servidor genera un UUID.

Esta transformación no cambia el estado ni las cabeceras ajenas al cuerpo. También se aplica a las repeticiones idempotentes según la cabecera X-Error-Format de la solicitud de repetición. Las respuestas correctas binarias siguen siendo binarias; sus errores JSON se envuelven. Las tablas restantes muestran los cuerpos predeterminados; aplicar las reglas anteriores proporciona el otro cuerpo posible para cada fila.

Notación de respuestas

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

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

PlainError = { error: string }

error y el texto de los mensajes de validación son descriptivos, no un discriminador programático estable. Basa la lógica en code cuando esté presente. La validación de solicitudes devuelve 422 ValidationError; validar un objeto completo puede producir { "validationErrors": {} } si no se identifica un campo individual. El JSON no válido y los fallos inesperados devuelven el 500 PlainError global mostrado a continuación.

Todos los ejemplos JSON muestran las estructuras exactas de los cuerpos. El texto indicado como <message> es el mensaje de validación u operación devuelto y es una cadena JSON, no un valor literal entre signos de menor y mayor.

Orden de procesamiento de solicitudes

Las solicitudes se procesan en este orden:

1. configuración y autenticación de tokens de espacios de trabajo;
2. políticas del host y límites de solicitudes del token/espacio de trabajo;
3. filtrado según los derechos actuales;
4. validación y reserva de idempotencia para cada modificación;
5. comprobación de ámbitos del endpoint, validación de la solicitud y operación solicitada.

Por tanto, una solicitud de modificación con un token válido pero con ámbitos insuficientes sigue teniendo que enviar Idempotency-Key. Una respuesta de modificación completada con 403, 404, 409 o 422 se puede repetir con la misma clave y solicitud.

Respuestas de autenticación, políticas y límites de solicitudes

Estas respuestas pueden aparecer en cualquier endpoint /v2/admin registrado antes del procesamiento específico del endpoint.

El acceso a la API está incluido en todos los planes. Desactivar el ajuste adminApiEnabled del host del espacio de trabajo devuelve 404; perder el derecho a una función adicional solo elimina los ámbitos afectados. La denegación del ámbito resultante utiliza la respuesta siguiente, no un proceso de renovación del token.

Fallos de ámbitos, idempotencia, análisis, propiedad e imprevistos

Los ID de recursos de la ruta deben ser números positivos. Un :siteId, :chargerId, :portId, :tariffId, :profileId, :assignmentId, :userId, :rfidId, :accessId, :limitId o :localUserId no positivo o no numérico devuelve 422 ValidationError, no 400.

Errores de emplazamientos y gestión de potencia

Errores de cargadores

mapChargerErrors() se utiliza para crear/actualizar cargadores, credenciales, ajustes de conectores, publicación, resolución de datos QR, modificación/recarga de configuración, inicio de firmware, los cuatro comandos básicos y la solicitud de programación compuesta.

Las operaciones de lectura simples solo devuelven las respuestas compartidas 401/403/404/429/500/503, además de 422 para la validación de consultas y rutas. La eliminación de un cargador puede devolver la respuesta compartida 500 PlainError si falla sin un error más específico.

Errores de informes

La exportación correcta es binaria; todos los errores de exportación siguen siendo JSON.

Errores de tarifas

Errores de perfiles de carga

Errores del dominio de usuarios

Los errores de validación de usuarios que identifican un campo utilizan ValidationError más code; los demás errores de usuarios utilizan CodedError. Todos los casos de recursos no encontrados utilizan la respuesta compartida RESOURCE_NOT_FOUND, que no revela la existencia del recurso.

POST /users/invitations también puede devolver la respuesta compartida 403 INSUFFICIENT_SCOPE tras analizar el cuerpo si falta users:access, o si se proporcionó un RFID y falta users:rfid. Los endpoints de usuarios locales enumeran todos los ámbitos obligatorios en la Referencia de endpoints.

Los códigos de error de usuarios se aplican así:

Todos los resultados de propiedad y recurso no encontrado de esas familias, incluido un correo no registrado en POST /users, utilizan el cuerpo compartido 404 RESOURCE_NOT_FOUND.

Respuestas sin cuerpo y de repetición

Una respuesta 204 correcta no tiene cuerpo. Esto se aplica a todas las eliminaciones documentadas que indican 204 empty. Una repetición idempotente completada establece Idempotency-Replayed: true y utiliza el estado y el cuerpo guardados; para 204, la respuesta HTTP sigue sin cuerpo. La API nunca devuelve un objeto JSON de éxito para una operación 204 documentada.