Weegloo Docs - Errores

Cuando una solicitud falla, WEEGLOO devuelve un cuerpo de error con un formato coherente junto con un código de estado HTTP. La forma del cuerpo de la respuesta es la misma independientemente de en qué API (CMA, CDA, ACMA, ACDA, Upload, Auth) se haya producido el fallo. Por eso, si sabes tratar un solo formato, puedes gestionar todos los errores con la misma lógica de ramificación. Esta página reúne en un solo lugar ese formato común y los códigos de error que se encuentran con más frecuencia.

Formato de la respuesta de error

El cuerpo del error tiene la siguiente forma. A continuación se muestra la respuesta recibida al consultar un WebHosting inexistente.

{
  "requestId": "GeR3sEbvWdgvv9eW2NXeanpj2wo6qbkVXgIW7Qd3ea6",
  "sys": {
    "id": "RxcgyPTSuk4GDy6s",
    "type": "NotFound",
    "code": "WGL404001",
    "timestamp": 1781785683556
  },
  "details": {
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } }
  },
  "reason": "WebHosting(...) has been deleted or does not exist.",
  "suggestion": "Please verify WebHosting and try again."
}

El significado de cada clave es el siguiente.

Clave	Tipo	Descripción
`requestId`	string	Identificador de rastreo de esta solicitud. Si lo aportas al contactar con soporte, podrán localizar rápidamente la solicitud correspondiente.
`sys.type`	string	Clasificación del error. Indica la categoría principal: `Unauthorized`, `Forbidden`, `NotFound`, `Unprocessable`, `Conflict`, `TooManyRequest`, etc.
`sys.code`	string	Código de error detallado (por ejemplo, `WGL409005`). Usa este valor cuando ramifiques la lógica por código.
`sys.timestamp`	integer	Momento en que se produjo el error (epoch en milisegundos).
`reason`	string	Motivo del fallo en lenguaje legible.
`suggestion`	string	Pista que ayuda a resolverlo.
`details`	object (opcional)	Información adicional. Incluye un `Refer` que apunta al recurso relacionado, una lista de elementos de error de validación (`errors`), etc. Puede no estar presente según el tipo de error.

La ramificación se hace por la unidad que necesites: sys.type (categoría principal) o sys.code (código detallado). Aunque el sys.type sea el mismo, si el sys.code es distinto la causa es distinta; por eso, si necesitas un tratamiento preciso, básate en sys.code.

Cuando falla la validación, en details.errors se incluyen los elementos que no cumplen. A continuación se muestra una respuesta en la que la validación falló al incluir en el cuerpo una propiedad que no existe en el esquema.

{
  "requestId": "yJ8KpQ2mWtnLrZ4Xv7BcEadfh3sNuMvKbGT5Pq9wRsx",
  "sys": {
    "id": "Lm2Nq9Tr8KdW4xZc",
    "type": "BadRequest",
    "code": "WGL400006",
    "timestamp": 1781776000000
  },
  "details": {
    "errors": [
      { "path": "", "message": "property 'X' is not defined in the schema", "property": "X" }
    ]
  },
  "reason": "Some values do not satisfy validation rules.",
  "suggestion": "Please check the request body and try again."
}

Cada elemento de details.errors contiene la posición que no cumple (path), la descripción (message) y el nombre de la propiedad relacionada (property). Si hay varios elementos, se incluye uno por cada valor que no cumple.

Códigos más frecuentes

A continuación se muestran los códigos de error que se encuentran con más frecuencia.

Código	Clasificación	Significado	Situación habitual
`WEB401001`	`Unauthorized`	El token no es válido	El token Bearer de `Authorization` ha caducado o es incorrecto.
`WGL403001`	`Forbidden`	Sin permiso	El rol del llamante no permite esa operación.
`WGL404001`	`NotFound`	El recurso no existe o ha sido eliminado	Se consultó con un `sys.id` incorrecto, o se llamó a una función aún no configurada (por ejemplo, un dominio personalizado sin conectar).
`WGL400006`	BadRequest	El valor del cuerpo no cumple las reglas de validación	El cuerpo se envió con una clave de campo o un tipo incorrectos. Los elementos que no cumplen se incluyen en `details.errors`.
`WGL409005`	`Conflict`	El recurso se ha modificado entretanto	Falta la cabecera `X-Weegloo-Version` o difiere de la versión actual (consulta Convenciones).
`WGL422007`	`Unprocessable`	No se puede archivar por estar publicado	Para archivar un Content o un Media, primero hay que anular su publicación.
`WGL422009`	`Unprocessable`	No se puede eliminar por estar publicado	Para eliminar un Content o un Media publicado, primero hay que anular su publicación.
`WGL429001`	`TooManyRequest`	Límite del plan superado	El número de recursos creados, como Organization o Space, ha superado el límite del plan actual. Si subes de plan, el límite aumenta.

Los códigos anteriores son solo una parte de los que se encuentran con frecuencia. Además de estos, puede haber muchos más códigos según la operación o el recurso. Sea cual sea el código que recibas, identifica la categoría principal con sys.type y comprueba la causa concreta y la dirección de la solución con reason y suggestion.

Convenciones: regla de concurrencia de X-Weegloo-Version para evitar WGL409005.
Propiedades del sistema (sys): el estado de publicación (status) y el ciclo de vida al que apuntan WGL422007 y WGL422009.

Formato de la respuesta de error

Códigos más frecuentes

Documentos relacionados