Errores
Todo error llega con la misma forma. Decide con code, que no cambia nunca dentro de v1; message es para una persona y puede mejorar con el tiempo.
La forma
{
"error": {
"code": "whatsapp_window_closed",
"message": "Se cerraron las 24 horas para escribirle a este contacto por WhatsApp. Envíale una plantilla aprobada para reabrir la conversación.",
"field": null,
"details": {
"window_closed_at": "2026-09-25T18:02:11.000Z",
"suggestion": "template"
},
"doc_url": "https://panel.adsmartbot.com/ayuda/api/errores#whatsapp_window_closed",
"request_id": "7b0c2d4e-1a2b-4c3d-8e9f-0a1b2c3d4e5f"
}
}fielddice qué dato falló (actions[1].type,fields.talla). Con varios errores a la vez, vienen todos endetails.errors.request_ides el mismo que la cabeceraRequest-Id: con él, el soporte encuentra tu petición.- Un id de otra cuenta responde 404, nunca 403: así no se revela que existe.
400
invalid_json«El cuerpo no es un JSON válido.»
Qué hacer: Revisa que el cuerpo sea JSON bien formado (comillas dobles, sin comas de sobra) y que vaya con Content-Type: application/json.
missing_parameter«Falta el dato «…».»
Qué hacer: Agrega el dato que dice error.field. La referencia de cada operación dice cuáles son obligatorios.
invalid_parameter«El dato «…» no es válido: revisa su formato.»
Qué hacer: Corrige el dato que dice error.field. Si hay varios errores, vienen todos en details.errors.
date_without_timezone«La fecha «…» tiene que llevar zona horaria, por ejemplo 2026-09-27T10:00:00-05:00.»
Qué hacer: Envía las fechas con hora en ISO 8601 con su zona (-05:00) o en UTC (terminadas en Z). Sin zona no se adivina: una cita quedaría corrida una o dos horas.
invalid_phone«El teléfono no es válido. Escríbelo con el indicativo del país, por ejemplo +57 300 123 4567.»
Qué hacer: Envía el número completo, con el indicativo del país. Se aceptan espacios, guiones y el «+».
invalid_cursor«El cursor no es válido o cambiaron los filtros. Empieza la lista de nuevo.»
Qué hacer: Pide la primera página sin cursor y recorre la lista con el next_cursor de cada respuesta, sin cambiar los filtros a mitad de camino.
key_in_url«No envíes la clave de acceso en la dirección: ponla en la cabecera Authorization. Si la clave era válida, quedó marcada como expuesta y deja de funcionar en 7 días: rótala en Configuración → Integraciones → API y avisos.»
Qué hacer: Envía la clave solo en la cabecera Authorization: Bearer … y rota la que quedó expuesta: una dirección web queda guardada en registros de servidores y navegadores.
401
missing_api_key«Falta la clave de acceso. Envíala en la cabecera Authorization: Bearer …»
Qué hacer: Crea una clave en Configuración → Integraciones → API y avisos y envíala en cada petición en la cabecera Authorization.
invalid_api_key«Esa clave de acceso no existe en esta plataforma. Revisa que la copiaste completa.»
Qué hacer: Copia la clave completa (empieza por ak_live_). Si la perdiste, crea otra: por seguridad no se vuelve a mostrar.
expired_api_key«Esta clave de acceso caducó el día de su vencimiento. Crea otra en Configuración → Integraciones → API y avisos.»
Qué hacer: Crea una clave nueva y cámbiala en tu sistema. Para cambiar una clave sin cortar el servicio, usa «Rotar» antes de que caduque.
revoked_api_key«Esta clave de acceso se revocó el día en que se revocó.»
Qué hacer: Una clave revocada no vuelve a funcionar. Pídele al dueño de la cuenta una nueva.
402
account_payment_required«La cuenta tiene un pago pendiente. La API vuelve a funcionar cuando se ponga al día.»
Qué hacer: El dueño de la cuenta lo resuelve en Plan y facturación. Mientras tanto solo responden GET /me y GET /account.
plan_contact_limit«La cuenta llegó a los contactos de su plan. Para agregar más, amplía el plan o suma contactos adicionales.»
Qué hacer: Amplía el plan o suma contactos adicionales en Plan y facturación. En la prueba gratis el tope cuenta los contactos creados, también los que ya se borraron.
email_quota_exhaustedllega en una versión próxima«Se acabaron los correos de este mes (). Se renuevan el próximo periodo, o se pueden sumar correos adicionales.»
Qué hacer: Espera a la renovación o suma correos adicionales en Plan y facturación.
403
insufficient_permissions«Esta clave de acceso no tiene el permiso «…». Pídele al dueño de la cuenta que se lo agregue.»
Qué hacer: El dueño o un administrador agrega el permiso en «Cambiar permisos» de la clave; vale en menos de 30 segundos. error.field dice qué acción o qué include lo pidió.
module_disabled«Esta función no está disponible en esta cuenta.»
Qué hacer: Ese módulo está apagado para la cuenta. Consulta con quien administra la plataforma.
not_available_in_trial«Esto no está disponible en la prueba gratis: se habilita al elegir un plan.»
Qué hacer: Se habilita al elegir un plan en Plan y facturación.
account_suspended«La cuenta está suspendida.»
Qué hacer: Consulta con quien administra la plataforma.
404
not_found«No existe eso en esta cuenta.»
Qué hacer: Revisa el id. Un id de otra cuenta también responde 404: cada clave solo ve lo de su cuenta.
route_not_found«Esa dirección no existe en la API. Revisa la documentación.»
Qué hacer: Revisa la ruta y la versión (/api/v1/…) en la referencia.
405
method_not_allowed«Esa dirección no acepta ese método.»
Qué hacer: La referencia dice qué métodos acepta cada dirección; la cabecera Allow de la respuesta también.
409
already_exists«Ya existe uno con ese nombre.»
Qué hacer: Usa el que ya existe: su id viene en details.existing_id.
contact_blocked«Este contacto está bloqueado. Desbloquéalo para escribirle.»
Qué hacer: Desbloquéalo desde la bandeja o con PATCH /contacts/{id} y "blocked": false.
contact_unsubscribed«Este contacto se dio de baja de la publicidad: no se le puede enviar una plantilla de marketing.»
Qué hacer: A quien se dio de baja solo le salen plantillas de utilidad o de autenticación.
contact_opted_out«Este contacto pidió no recibir mensajes: solo él puede volver a suscribirse escribiéndote.»
Qué hacer: Respeta la baja: ni la API ni el panel pueden volver a suscribir a quien se dio de baja por su cuenta.
whatsapp_opt_in_required«Este contacto nunca te ha escrito. Para enviarle una plantilla hace falta la prueba de que aceptó recibir WhatsApp: envía whatsapp_opt_in con su fuente y su evidencia.»
Qué hacer: Guarda el permiso con POST /contacts/{id}/whatsapp-consent, o envíalo en la misma petición con whatsapp_opt_in: { source, evidence, captured_at }.
contact_readonly_field«Este contacto ya te escribió por WhatsApp: su teléfono lo pone WhatsApp y no se cambia por la API.»
Qué hacer: No envíes phone para ese contacto. Si la persona cambió de número, llegará como un contacto nuevo cuando escriba desde él.
conversation_with_team«Tu equipo está atendiendo a este cliente y enviaste "skip_if_team_attending": true, así que el flujo no se lanzó.»
Qué hacer: Espera a que tu equipo le devuelva el chat a la IA, o envíalo sin "skip_if_team_attending": sin ese campo, el flujo se lanza aunque tu equipo esté atendiendo, como un mensaje masivo.
whatsapp_window_closed«Se cerraron las 24 horas para escribirle a este contacto por WhatsApp. Envíale una plantilla aprobada para reabrir la conversación.»
Qué hacer: Envía una plantilla aprobada (type: "template"). whatsapp_windows en el contacto dice, por número, si la ventana está abierta.
channel_not_available«Ese canal no está disponible: no está conectado.»
Qué hacer: Revisa el canal en Configuración → Canales. GET /channels dice su estado, su último error y si tiene las automatizaciones encendidas (automations_enabled): con ellas apagadas el canal se atiende solo a mano.
flow_not_launchable«Ese flujo no se puede lanzar: no está activo.»
Qué hacer: Publica y activa el flujo en el editor. GET /flows?launchable=true lista los que se pueden lanzar.
flow_already_running«El contacto ya va por ese flujo. Envía "allow_repeat": true si quieres que entre otra vez.»
Qué hacer: Envía "allow_repeat": true, o cancela lo que espera con POST /contacts/{id}/flow-runs/cancel.
calendar_limit_reachedllega en una versión próxima«El contacto ya tiene el máximo de citas de este calendario.»
Qué hacer: Revisa los topes del calendario en Herramientas → Calendarios.
email_not_allowedllega en una versión próxima«No se le puede enviar este correo: se dio de baja.»
Qué hacer: Respeta la baja y las direcciones bloqueadas.
idempotency_in_progress«Esa petición todavía se está haciendo. Vuelve a intentar en unos segundos.»
Qué hacer: Espera unos segundos y repite con la misma Idempotency-Key: recibirás la respuesta de la primera.
subscription_limit«Llegaste al máximo de avisos a otros sistemas en esta cuenta.»
Qué hacer: Borra los avisos que ya no uses. Zapier, Make, n8n y Pabbly solo cuentan para el máximo de la cuenta.
subscription_managed_elsewhere«Este aviso lo creó el panel u otra clave: solo se cambia desde Configuración → Integraciones → API y avisos.»
Qué hacer: Cada clave solo toca los avisos que ella creó.
413
payload_too_large«El cuerpo pasa de 1 MB.»
Qué hacer: Envía menos datos por petición.
415
unsupported_media_type«Envía el cuerpo como JSON (Content-Type: application/json).»
Qué hacer: Pon la cabecera Content-Type: application/json y envía el cuerpo en JSON.
422
idempotency_key_reused«Ya usaste esa Idempotency-Key con otros datos.»
Qué hacer: Usa una clave distinta para cada operación distinta, por ejemplo con el número de pedido y lo que haces: pedido-A-1043-enviado.
invalid_field_value«El valor del campo «…» no es válido.»
Qué hacer: GET /fields dice el tipo y las opciones de cada campo.
template_not_found«No hay una plantilla aprobada llamada «…» en ese idioma en el número elegido.»
Qué hacer: GET /whatsapp/templates lista las aprobadas de cada número, con su nombre e idioma exactos.
template_parameters«La plantilla «…» lleva ? variables en el mensaje y llegaron ?.»
Qué hacer: Envía en body tantas variables como {{1}}, {{2}}… tenga el texto de la plantilla.
invalid_contentllega en una versión próxima«El contenido no es válido.»
Qué hacer: Revisa los topes de cada canal en /ayuda/api/limites.
media_unreachablellega en una versión próxima«No se pudo descargar el archivo de esa dirección: no respondió.»
Qué hacer: La dirección tiene que ser pública (https) y devolver el archivo directamente.
media_too_largellega en una versión próxima«El archivo pesa ? MB y WhatsApp acepta hasta ? MB para ese tipo.»
Qué hacer: Reduce el archivo o envíalo como enlace en un texto.
phone_required«Para crear un contacto hace falta su teléfono.»
Qué hacer: Envía phone con el indicativo del país. Los contactos solo con correo llegan más adelante.
invalid_entry_block«Ese bloque no existe en el flujo publicado, o es una nota. Usa el id de uno de entry_blocks (GET /flows/{id}).»
Qué hacer: Copia el id del bloque en el editor (abajo del panel del bloque) o léelo en entry_blocks de GET /flows/{id}. Vale lo que está publicado: si el bloque es nuevo, publica el flujo primero.
429
rate_limited«Demasiadas peticiones. Vuelve a intentar en unos segundos.»
Qué hacer: Espera los segundos de Retry-After y repite con la misma Idempotency-Key. details.limit dice qué límite se pasó.
500
internal_error«Algo falló de nuestro lado. Quedó anotado con el número de esta petición.»
Qué hacer: Repite la petición con la misma Idempotency-Key. Si sigue fallando, escribe al soporte con el request_id.
502
whatsapp_error«WhatsApp no aceptó el envío: respondió con un error.»
Qué hacer: details.meta_code trae el código de Meta. El mensaje explica qué hacer.
email_provider_errorllega en una versión próxima«El servicio de correo no aceptó el envío: respondió con un error.»
Qué hacer: Vuelve a intentar en unos minutos.