Errores

La API usa los códigos HTTP de siempre: 2xx salió bien, 4xx hay algo para corregir en la llamada o en la cuenta, 5xx falló algo de nuestro lado o de Meta.

Formato

Casi todos los errores tienen esta forma:

{
  "error": "Pasaron más de 24 horas desde el último mensaje del cliente. Para escribirle, usá una plantilla.",
  "cause": null
}

error: explica el problema en español. Está pensado para mostrarlo tal cual a tu equipo.
cause: detalle para tu código. Es null salvo en los errores de plan (402).

Los mensajes de error usan el español de Argentina (“usá”, “elegí”), igual que la app de eltick.

Errores de validación

Cuando al cuerpo o a los parámetros les falta algo o tienen un tipo equivocado, la respuesta 400 tiene otra forma: error.message es un JSON (en texto) con la lista de problemas. path dice qué campo y message por qué.

{
  "success": false,
  "error": {
    "name": "ZodError",
    "message": "[\n  {\n    \"expected\": \"string\",\n    \"code\": \"invalid_type\",\n    \"path\": [\n      \"phone\"\n    ],\n    \"message\": \"Invalid input: expected string, received undefined\"\n  }\n]"
  }
}

Para leerlo:

const body = await res.json()
const problems = body.success === false ? JSON.parse(body.error.message) : []
// [{ path: ["phone"], message: "Invalid input: expected string, received undefined", ... }]

Códigos

400 · Datos inválidos

Algo del pedido no es válido. Los casos más comunes:

Falta un campo obligatorio (phone en contactos, to en mensajes).
Mandaste text y template a la vez, o ninguno de los dos: “Mandá text o template, uno de los dos.”
El teléfono no es válido: “El teléfono “123” no es válido. Usá formato internacional, por ejemplo +5491123456789.” Revisa Formato de teléfonos.
limit fuera de rango (1 a 200) o after que no es un UUID.

Qué hacer: corrige el pedido. Reintentar igual va a fallar igual.

401 · Sin autenticación

Falta la clave, está mal escrita o fue revocada.

{ "error": "La clave de API no es válida o fue revocada.", "cause": null }

Qué hacer: revisa que el encabezado sea Authorization: Bearer etk_live_… y que la clave siga activa en Ajustes › API y webhooks.

402 · Tu plan no lo permite

La cuenta no tiene un plan que permita esto. cause.reason te dice por qué:

`reason`	Qué pasó
`feature`	El plan no incluye la API (`cause.feature` es `"api"`).
`paused`	La prueba gratis terminó o la cuenta está pausada.
`limit`	Llegaste al límite de contactos del plan. `cause.limit` y `cause.used` traen los números.

cause.suggested es el plan que lo resolvería.

{
  "error": "Tu plan incluye hasta 100.000 contactos. Pasate a Enterprise para sumar más.",
  "cause": {
    "type": "upgrade",
    "reason": "limit",
    "resource": "contacts",
    "plan": "escala",
    "limit": 100000,
    "used": 100000,
    "suggested": "enterprise"
  }
}

Qué hacer: avisa a quien administra la cuenta. Se resuelve en Ajustes › Plan y uso. El límite de contactos solo se aplica al crear contactos nuevos (con POST /contacts o al mandar un mensaje a un teléfono que no estaba).

404 · No existe

El recurso no existe en esta cuenta: “Mensaje no encontrado.” o “La plantilla ya no existe.”Qué hacer: revisa el id. Los ids son de cada cuenta: una clave no ve lo de otra cuenta.

409 · No se puede mandar ahora

El pedido es válido, pero WhatsApp no deja hacerlo en este momento:

“Pasaron más de 24 horas desde el último mensaje del cliente. Para escribirle, usá una plantilla.” → manda una plantilla en vez de text.
“La plantilla todavía no está aprobada por Meta.” → espera la aprobación o usa otra.
“No hay un número de WhatsApp conectado con ese id.” → revisa phoneNumberId.
“Tu WhatsApp está desconectado.” → vuelve a conectar el número en Ajustes › Números y canales.

Qué hacer: no reintentes a ciegas; cambia el pedido o resuelve el estado de la cuenta.

502 · Meta rechazó el mensaje

Meta no aceptó el envío. El mensaje incluye el motivo que dio Meta, por ejemplo:

{ "error": "WhatsApp no aceptó el mensaje: (#131030) Recipient phone number not in allowed list", "cause": null }

Qué hacer: lee el motivo. Algunos son temporales (reintenta en unos minutos) y otros son de la cuenta de Meta, como que falte el medio de pago. Mira Cargar el medio de pago.

500 · Error inesperado

{ "error": "Algo salió mal. Volvé a intentar en unos segundos." }

Qué hacer: reintenta con espera creciente (1 s, 2 s, 4 s…). Si se repite, escríbenos a soporte@eltick.com con la hora y el endpoint.

Mensajes que se aceptan pero después fallan

Un 201 en POST /messages quiere decir que Meta aceptó el mensaje, no que ya llegó. La entrega puede fallar después: por ejemplo, si el número no tiene WhatsApp. En ese caso el mensaje queda con status: "failed" y un código de Meta:

{
  "status": "failed",
  "errorCode": 131026,
  "errorTitle": "Message undeliverable"
}

Lo ves con GET /messages/{id} o con el webhook message.status. Códigos de Meta frecuentes:

Código	Qué significa
`131026`	No se pudo entregar: el número no tiene WhatsApp o no acepta mensajes de empresas.
`131049`	Meta no lo entregó para cuidar la experiencia del usuario (demasiados mensajes de marketing recibidos). Prueba otro día.
`131050`	El usuario dejó de aceptar mensajes de marketing de tu empresa.
`131047`	Pasaron más de 24 horas: hacía falta una plantilla.
`131042`	Hay un problema con el medio de pago de tu cuenta de Meta.

Reintentos seguros

Reintenta solo 500, 502 temporales y errores de red.
POST /contacts se puede reintentar sin problema: si el contacto ya existe, lo actualiza.
POST /messages no es idempotente: si reintentas después de un timeout, el cliente podría recibir el mensaje dos veces. Antes de reintentar, fíjate si el mensaje ya aparece en el chat o guarda el id de la primera respuesta.

Empieza aquí

Webhooks

Recetas

Referencia

Formato

Errores de validación

Códigos

Mensajes que se aceptan pero después fallan

Reintentos seguros

​Formato

​Errores de validación

​Códigos

​Mensajes que se aceptan pero después fallan

​Reintentos seguros

Formato

Errores de validación

Códigos

Mensajes que se aceptan pero después fallan

Reintentos seguros