Categorías de Errores

Esta guía te ayuda a entender y resolver los errores que puedes encontrar al usar la API de Aleluya.

Estructura de Respuesta de Error

La API de Aleluya utiliza estructuras de error consistentes en formato JSON. La forma puede variar según el tipo de error.

Error Básico

Todas las respuestas de error siguen esta estructura consistente:

{
  "error": [
    {
      "message": "Descripción legible del error",
      "code": "0001",
      "object": "nombre_del_objeto",
      "index": 0
    }
  ]
}

Ejemplo:

{
  "error": [
    {
      "message": "Correo electrónico ya está en uso.",
      "code": "0003",
      "object": "email",
      "index": 0
    }
  ]
}

Esto te indica que:

• 📝 message: El correo ya está registrado en Aleluya
• 🔢 code: 0003 identifica este error como un problema de duplicidad
• 📦 object: El campo con problema es email
• 📍 index: Posición 0 (es el primer registro o un registro único)

Campos de Error

Errores de Validación de Recursos

Cuando creas o actualizas un recurso (como un cargo, contrato, o nómina), la API puede identificar varios problemas a la vez. Cada error te indica qué campo específico tiene un problema.

Ejemplo: Intentas crear un registro, pero olvidas llenar campos requeridos y usas un correo inválido

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Nombre no puede estar en blanco.",
      "code": "0002",
      "object": "name",
      "index": 0
    },
    {
      "message": "Correo electrónico es inválido.",
      "code": "0101",
      "object": "email",
      "index": 0
    },
    {
      "message": "Número de documento ya está en uso.",
      "code": "0003",
      "object": "id_number",
      "index": 0
    }
  ]
}

📘

¿Por qué todos tienen index: 0?

En este caso estás creando o actualizando un solo registro. Todos los errores pertenecen al mismo elemento, por eso todos tienen index: 0.

Si estuvieras creando múltiples registros a la vez y varios fallaran, cada uno tendría un index diferente (0, 1, 2, etc.) indicando su posición en el array que enviaste.

Errores en Operaciones con Múltiples Elementos

Algunos endpoints te permiten enviar varios elementos a la vez (por ejemplo, actualizar 4 cargos en una sola petición en lugar de hacer 5 peticiones separadas). Cuando uno o más elementos tienen errores, el campo index te indica exactamente cuál elemento falló.

Ejemplo Real: Actualizas varios cargos de tu empresa, pero algunos tienen problemas

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Nombre no puede estar en blanco.",
      "code": "0002",
      "object": "name",
      "index": 1
    },
    {
      "message": "Nombre ya está en uso.",
      "code": "0003",
      "object": "name",
      "index": 3
    }
  ]
}

¿Qué significa este error?

• index: 1 → El segundo cargo (recuerda que se cuenta desde 0) tiene error en el campo name.
• index: 3 → El cuarto cargo también tiene error en el campo name.
• object: "name" → El campo problemático es el nombre en ambos casos.

¿Qué hacer?

1. Corrige el cargo en la posición 1 (index 1) agregando un nombre.
2. Corrige el cargo en la posición 3 (index 3) con un nombre único.
3. Reenvía los 4 cargos completos (no solo los que fallaron).

Importante:

• El campo index indica la posición del registro en tu array original, no la posición del error.
• Si envías 4 cargos y el cargo en posición 1 y el cargo en posición 3 tienen errores, recibirás index: 1 e index: 3.
• Si un registro tiene múltiples errores de validación, todos esos errores tendrán el mismo index.

Ejemplo: Si el cargo en posición 1 tiene el nombre vacío Y es muy largo, recibirás 2 errores, ambos con index: 1.

📘

En operaciones con múltiples registros, si uno o más fallan, ningún cambio se guarda. Debes corregir los elementos con error y reenviar la petición completa.

Guía Rápida: Tipos de Errores

Todos los errores de la API incluyen un código HTTP que indica el tipo general del problema. Usa esta tabla para identificar rápidamente qué está pasando:

Catálogo de Errores

A continuación encontrarás todos los tipos de errores organizados por código HTTP, con ejemplos y explicaciones detalladas.

401 Errores de Autenticación

El token es inválido, ha expirado, o las credenciales proporcionadas son incorrectas.

Usuario no autenticado

Credenciales inválidas o token no válido.

401 Unauthorized

{
  "error": [
    {
      "message": "Credenciales inválidas.",
      "code": "0001",
      "object": "user",
      "index": 0
    }
  ]
}

Usuario inactivo

El usuario está inactivo en Aleluya.

401 Unauthorized

{
  "error": [
    {
      "message": "El usuario está inactivo. Contacta al administrador de la cuenta para activar este usuario.",
      "code": "0002",
      "object": "user",
      "index": 0
    }
  ]
}

Usuario bloqueado

La cuenta ha sido bloqueada temporalmente debido a múltiples intentos fallidos de inicio de sesión.

401 Unauthorized

{
  "error": [
    {
      "message": "Su cuenta ha sido bloqueada temporalmente debido a múltiples intentos fallidos de inicio de sesión. Si su cuenta existe en Aleluya, en pocos minutos recibirá un correo electrónico con las instrucciones para desbloquearla.",
      "code": "0003",
      "object": "user",
      "index": 0
    }
  ]
}

402 Errores de Pago Requerido

La acción solicitada requiere una suscripción activa, un plan superior, o el periodo de prueba ha finalizado.

Periodo de prueba finalizado

El periodo de prueba ha finalizado.

402 Payment Required

{
  "error": [
    {
      "message": "El periodo de prueba ha finalizado.",
      "code": "0001",
      "object": "company",
      "index": 0
    }
  ]
}

Suscripción vencida

La suscripción ha vencido.

402 Payment Required

{
  "error": [
    {
      "message": "Suscripción vencida.",
      "code": "0002",
      "object": "company",
      "index": 0
    }
  ]
}

Suscripción cancelada

La suscripción ha sido cancelada.

402 Payment Required

{
  "error": [
    {
      "message": "Suscripción cancelada.",
      "code": "0003",
      "object": "company",
      "index": 0
    }
  ]
}

403 Errores de Permisos

El usuario no tiene los permisos necesarios para realizar esta acción.

Usuario no autorizado

Permisos insuficientes para realizar la acción solicitada.

403 Forbidden

{
  "error": [
    {
      "message": "No tienes permisos para realizar esta acción.",
      "code": "0001",
      "object": "user",
      "index": 0
    }
  ]
}

404 Errores de Recurso No Encontrado

El recurso solicitado no existe o no está disponible.

Recurso no encontrado

El recurso especificado no existe en Aleluya.

404 Not Found

{
  "error": [
    {
      "message": "Persona no existe",
      "code": "0001",
      "object": "worker",
      "index": 0
    }
  ]
}

URL no existe

La URL solicitada no existe.

404 Not Found

{
  "error": [
    {
      "message": "La url solicitada no existe.",
      "code": "0002",
      "object": "request",
      "index": 0
    }
  ]
}

408 Errores de Timeout

La solicitud excedió el tiempo de espera máximo permitido.

Se excedió el tiempo de espera

La respuesta está tardando demasiado tiempo.

408 Request Timeout

{
  "error": [
    {
      "message": "La respuesta se está demorando mucho. Intenta nuevamente.",
      "code": "0001",
      "object": "request",
      "index": 0
    }
  ]
}

422 Errores de Validación

La solicitud no pudo ser procesada debido a errores de validación en los datos enviados.

Errores de Presencia

Campo requerido

Un campo requerido no está presente.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Nombre debe existir.",
      "code": "0001",
      "object": "name",
      "index": 0
    }
  ]
}

Campo en blanco o vacio

Un campo no puede estar en blanco.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Correo electrónico no puede estar en blanco.",
      "code": "0002",
      "object": "email",
      "index": 0
    }
  ]
}

Errores de Unicidad

campo ya está en uso

El valor ya está siendo utilizado por otro registro.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Correo electrónico ya está en uso.",
      "code": "0003",
      "object": "email",
      "index": 0
    }
  ]
}

Errores de Validación de Datos

Datos inválidos

Los datos enviados en la petición son inválidos.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Los datos enviados son inválidos.",
      "code": "0102",
      "object": "request",
      "index": 0
    }
  ]
}

Valor fuera de las opciones válidas

El valor no está incluido en las opciones válidas (típicamente para enums).

422 Unprocessable Entity

{
  "error": [
    {
      "message": "pending es inválido para Estado.",
      "code": "0104",
      "object": "status",
      "index": 0
    }
  ]
}

Errores de Longitud

Valor demasiado corto

El valor es demasiado corto.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Contraseña es demasiado corto (8 caracteres mínimo).",
      "code": "0201",
      "object": "password",
      "index": 0
    }
  ]
}

Valor demasiado largo

El valor es demasiado largo.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Nombre es demasiado largo (100 caracteres máximo).",
      "code": "0202",
      "object": "name",
      "index": 0
    }
  ]
}

Errores Numéricos

Valor no es un número

El valor debe ser un número.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Salario no es un número.",
      "code": "0301",
      "object": "base_salary",
      "index": 0
    }
  ]
}

Valor debe ser menor a un límite

El valor debe ser menor a un límite específico.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Edad debe ser menor a 100.",
      "code": "0302",
      "object": "age",
      "index": 0
    }
  ]
}

Valor debe ser mayor a un límite

El valor debe ser mayor a un límite específico.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Salario debe ser mayor a 0.",
      "code": "0304",
      "object": "base_salary",
      "index": 0
    }
  ]
}

Errores de Formato

Tamaño de archivo excedido

El archivo excede el tamaño máximo permitido.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Logo es muy grande. Su peso máximo debe ser 1 MB.",
      "code": "0306",
      "object": "logo",
      "index": 0
    }
  ]
}

Formato de imagen inválido

El formato de la imagen no es válido.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Logo debe ser una imagen en formato png o jpg.",
      "code": "0307",
      "object": "logo",
      "index": 0
    }
  ]
}

Formato de documento debe ser PDF

El documento debe estar en formato PDF.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Documento debe ser un PDF.",
      "code": "0309",
      "object": "affiliation",
      "index": 0
    }
  ]
}

Errores de Fechas

Fechas cruzadas

No es posible tener dos elementos con fechas cruzadas.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "No es posible tener dos elementos con fechas cruzadas.",
      "code": "0404",
      "object": "initial_day",
      "index": 0
    }
  ]
}

Fecha fuera de rango

La fecha está fuera del rango permitido.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Fecha inicial no puede ser modificada. La fecha es menor al periodo editable.",
      "code": "0406",
      "object": "initial_day",
      "index": 0
    }
  ]
}

Formato de fecha inválido

El formato de la fecha es inválido.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "El formato de la fecha es inválido.",
      "code": "0412",
      "object": "date",
      "index": 0
    }
  ]
}

Errores de Eliminación

Recurso no se puede eliminar

El recurso no puede ser eliminado.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Periodo no se puede eliminar.",
      "code": "0501",
      "object": "period",
      "index": 0
    }
  ]
}

Nota: En errores de eliminación, el campo object indica el tipo de recurso que no puede eliminarse, no un campo específico.

Errores de Seguridad

Parámetros maliciosos

Los parámetros contienen contenido potencialmente malicioso.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "Los parámetros de la petición contienen contenido malicioso.",
      "code": "0122",
      "object": "request",
      "index": 0
    }
  ]
}

Contiene secuencias UTF-8 inválidas

La petición contiene secuencias UTF-8 inválidas.

422 Unprocessable Entity

{
  "error": [
    {
      "message": "La ruta de la petición contiene secuencias UTF-8 inválidas.",
      "code": "0128",
      "object": "request",
      "index": 0
    }
  ]
}

500 Errores del Servidor

Ocurrió un error inesperado en el servidor. Si un error interno ocurre, nuestros ingenieros son notificados automáticamente para investigar el problema.

Error interno del servidor

Error interno del servidor.

500 Internal Server Error

{
  "error": [
    {
      "message": "Ha ocurrido un error inesperado. Por favor, intenta nuevamente o contacta a soporte.",
      "code": "0001",
      "object": "request",
      "index": 0
    }
  ]
}

Preguntas Frecuentes

¿Por qué recibo múltiples errores a la vez?

La API valida todos los campos antes de guardar un recurso. Si varios campos tienen problemas, te los muestra todos de una vez para que puedas corregirlos en una sola corrección, en lugar de ir uno por uno.

¿Qué hago si recibo un error 500?

Los errores 500 indican un problema en el servidor. Recomendamos:

1. Espera 1-2 minutos.
2. Intenta la misma operación nuevamente.
3. Si el error persiste después de 2-3 intentos, contacta a soporte con el código de error.
4. Incluir toda la información del error: código HTTP (500), code, message, endpoint, y fecha/hora.

¿Qué significa "index" en los errores?

El index indica la posición de un elemento en un listado, comenzando desde 0. Por ejemplo:

• index: 0 = Primer elemento
• index: 1 = Segundo elemento
• index: 2 = Tercer elemento

Esto es útil cuando envías varios elementos a la vez y necesitas saber cuál tiene el problema.

¿Por qué ningún cambio se guardó si solo un elemento tenía error?

Para mantener la consistencia de tus datos, cuando envías múltiples elementos y uno falla, ninguno se guarda. Esto evita guardar información incompleta o inconsistente. Debes corregir los elementos con error y reenviar la petición completa.

Recursos Adicionales

• Documentación de la API: Consulta la documentación específica de cada endpoint para ver ejemplos y parámetros requeridos.