Copy page

Documentación

Errores

Todos los errores de la API siguen una estructura consistente en JSON. El código HTTP indica el tipo general del problema; el campo code identifica el error específico.

---

Estructura de un error

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

Campo	Tipo	Descripción
message	string	Descripción del error en español
code	string	Código único de 4 dígitos
object	string	Campo o recurso donde ocurrió el error
index	integer	Posición del registro en operaciones con múltiples elementos

Múltiples errores en una misma petición

La API valida todos los campos antes de guardar y devuelve todos los problemas a la vez — no uno por uno:

Code
{
  "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
    }
  ]
}

Operaciones con múltiples elementos

Cuando envías varios registros a la vez, el campo index indica cuál falló (0 = primero, 1 = segundo, etc.):

Code
{
  "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
    }
  ]
}

---

Códigos HTTP

Código	Significado	Qué hacer
401	Sesión expirada o credenciales incorrectas	Inicia sesión nuevamente
402	Plan vencido o cancelado	Actualiza tu suscripción
403	Sin permisos para esta acción	Contacta al administrador de tu cuenta
404	El recurso no existe	Verifica que el ID sea correcto
408	La petición tardó demasiado	Espera unos segundos e intenta de nuevo
422	Los datos enviados tienen errores	Revisa el campo message de cada error en la respuesta
429	Límite de peticiones excedido	Espera y reintenta con backoff — ver Límites
500	Error interno del servidor	Espera 1-2 minutos e intenta de nuevo

---

Errores transversales

Estos errores pueden aparecer en cualquier endpoint.

401 — Autenticación

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

Causas comunes: el api_access_token expiró (vigencia de 8 horas), las credenciales son incorrectas, o el usuario está inactivo o bloqueado. Consulta la guía de autenticación para más detalle.

403 — Permisos

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

El usuario autenticado no tiene el rol necesario para ejecutar esta operación. Consulta los roles disponibles en la guía de accesos.

429 — Rate limit

Code
{
  "error": [
    {
      "message": "Has excedido el límite de solicitudes permitidas. Por favor, intenta de nuevo más tarde.",
      "code": "0001",
      "object": "rate_limit",
      "index": 0
    }
  ]
}

500 — Error del servidor

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

---

Errores específicos por endpoint

Los errores 422 y otros errores de negocio están documentados directamente en cada endpoint de la referencia de la API. Busca la sección de respuestas del endpoint que estás usando para ver los códigos y mensajes posibles.