Genuka WA docs

Error 100 de WhatsApp: Invalid parameter — causa y solución

Error 100 de WhatsApp Cloud API (Invalid parameter): un parámetro desconocido, mal escrito o demasiado largo. Cómo leer details y corregir la solicitud.

El error 100 de WhatsApp significa que tu solicitud a la Cloud API contiene un parámetro que Meta no reconoce, uno mal escrito o un valor que supera un límite de longitud. Suele ser un error de contenido: volver a enviar la misma solicitud siempre fallará. La causa generalmente aparece en el campo details; con el subcódigo 33, lo que está mal es el ID al que apuntas.

¿Qué significa el error 100?

Meta lo clasifica entre los "otros errores" de la Cloud API:

"The request included one or more unsupported or misspelled parameters." — Meta, códigos de error de la Cloud API

La solución que sugiere Meta enumera cuatro comprobaciones: leer la referencia del endpoint para ver los parámetros admitidos y cómo se escriben; en WhatsApp Flows con endpoint, proporcionar una clave pública RSA válida de 2048 bits en formato PEM; asegurarte de que el phone_number_id que registras coincida con el almacenado anteriormente; y respetar las restricciones de longitud de cada tipo.

En la respuesta de Graph, message suele ser (#100) Invalid parameter, un título genérico. La información útil está en otra parte: Meta describe details como el campo que puede indicar "which parameter is invalid or what values are acceptable" (qué parámetro no es válido o qué valores se aceptan) (misma página).

¿Cuándo aparece el error 100?

SituaciónQué devuelve MetaFuente
Parámetro desconocido o mal escrito(#100) Invalid parameter, con el parámetro problemático en detailsMeta
Valor que supera un límite de longitudEl mismo códigoMeta
Clave pública de Flows que no es una clave RSA de 2048 bits en PEMEl mismo códigoMeta
Mensaje que no es de plantilla enviado a la Marketing Messages APIdetails: "Message must be a template message."Meta
ID de número de teléfono o de cuenta incorrecto, o un token sin acceso a ese activoerror_subcode: 33 y "Unsupported post request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation", sin detailsReportes de desarrolladores: Activepieces, Fast2SMS
Enviar desde un número a sí mismo(#100) Invalid parameter, sin ningún detalleObservación de Genuka
Eliminar una plantilla sin derechos sobre la cuenta de WhatsApp(#100) Need permission on either WhatsApp Business Account or owner/shared businessObservación de Genuka

Las dos últimas filas provienen de nuestras propias llamadas. Para un envío a uno mismo, Meta en realidad documenta un código específico, 131021 ("Sender and recipient phone number is the same"), pero lo que recibimos fue un 100 sin más.

¿Dónde lo ves en Genuka WA?

Genuka WA valida gran parte de la solicitud antes que Meta, y entonces responde sin que Meta vea nada:

Comprobación de GenukaRespuesta
Mensaje sin campo de contenido, multimedia sin assetId, id ni link400 missing_content, 400 invalid_media
Plantilla con componentes mal formados400 invalid_template (se puede desactivar con "validate": false)
to igual al número que envía400 recipient_is_sender

Cuando el rechazo viene de Meta, Genuka transmite el código 100 sin reclasificarlo: la clase es unknown, no reintentable.

400 — POST /api/v1/messages
{
  "error": "send_unknown",
  "message": "…the details text, when Meta provides one…",
  "meta": {
    "errorClass": "unknown",
    "retryable": false,
    "code": 100,
    "details": "…",
    "traceId": "AbC…"
  }
}

En POST /api/v1/templates, el mismo rechazo vuelve como 422 meta_rejected con el mismo objeto meta. Genuka nunca valida el campo raw de POST /api/v1/messages: los errores vuelven directamente de Meta (Enviar mensajes).

En una campaña MARKETING, un 100 de la Marketing Messages API hace que Genuka reenvíe el mensaje por el endpoint normal /messages; si este también lo rechaza, el destinatario pasa a failed.

¿Y el subcódigo 33?

No es un error de contenido. Con meta.code: 100 y meta.subcode: 33, y un mensaje que empieza por "Unsupported post request" (o "get" para una lectura), Graph indica que el objeto de destino no existe o que el token no tiene acceso a él. Las causas reportadas son un ID de número de teléfono o de cuenta de WhatsApp incorrecto, un token que perdió el acceso a ese activo o un acceso de socio que fue retirado (Fast2SMS). Con Genuka WA, consulta GET /api/v1/connections: un número cuyo estado ya no es connected corresponde a la página del error 200; un número eliminado del lado de Meta, a la página del error 33.

¿Cómo corrijo el error 100?

Lee meta.details. Es la única parte de la respuesta que nombra el problema. Regístralo junto con meta.traceId y el encabezado x-request-id.

Compara la solicitud con la referencia. Para los envíos, la referencia de la API y Enviar mensajes enumeran cada campo aceptado y sus límites: 4.096 caracteres para un texto, 1.024 para el pie de una imagen, 20 para el título de un botón, como máximo 3 botones de respuesta.

Quita lo que agregaste "por si acaso". Un campo de la Cloud API copiado en raw pero desconocido para el endpoint basta para provocar un 100.

Si details está vacío, reduce la solicitud. Envía el mismo mensaje simplificado (un text simple al mismo número) y luego vuelve a agregar los elementos uno por uno. Si un mensaje mínimo también falla, comprueba que to no sea el número que envía y contacta al soporte de Genuka con x-request-id y meta.traceId.

const response = await fetch("https://wa.genuka.com/api/v1/messages", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.GENUKA_WA_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ connectionId: "con_1", to: "+237690000001", text: "Tu paquete está en camino." }),
});
const json = await response.json();

if (!response.ok) {
  // Todo lo necesario para diagnosticar, sin volver a enviar la solicitud.
  console.error({
    status: response.status,
    error: json.error,
    metaCode: json.meta?.code,
    details: json.meta?.details ?? json.message,
    traceId: json.meta?.traceId,
    requestId: response.headers.get("x-request-id"),
  });
}

¿Cómo evito el error 100?

  • Mantén activada la validación de Genuka. En POST /api/v1/templates, solo pasa "validate": false para un componente que Meta acepta y nuestro validador rechaza.
  • Prefiere los campos tipados a raw. Los campos tipados se revisan en su forma antes del envío (campos obligatorios, multimedia sin id ni enlace); los límites de longitud y de cantidad los sigue aplicando Meta, y raw no se revisa en absoluto.
  • Prueba cada nuevo tipo de mensaje en un número de prueba antes de conectarlo a un envío masivo: un 100 es el mismo para todos los destinatarios.

Códigos de error relacionados

  • 131008: falta un parámetro obligatorio.
  • 131009: el parámetro existe, pero su valor no es válido.
  • 131021: el remitente y el destinatario son el mismo número.
  • 132000: la cantidad de variables enviadas no coincide con la plantilla.
  • 33: número eliminado (código 33), que no debe confundirse con el subcódigo 33 del código 100, que señala un objeto que no se encuentra o al que no se puede acceder (número eliminado o acceso perdido).
  • 200: se retiró el acceso a la cuenta de WhatsApp, o falta un permiso.

Preguntas frecuentes

¿Por qué details a veces está vacío?

Meta no siempre lo completa. Enviar desde un número a sí mismo, por ejemplo, vuelve como (#100) Invalid parameter sin nada más, y por eso Genuka WA lo comprueba antes.

¿Debo reintentar una solicitud rechazada con 100?

No. El problema es el contenido, o el ID de destino con el subcódigo 33: la misma solicitud producirá el mismo error. Corrígela primero.

¿Qué diferencia hay entre el error 100 y el error 131009?

Meta describe el 100 como un parámetro no admitido o mal escrito, y el 131009 como un parámetro conocido cuyo valor no es válido. Ambos se corrigen leyendo details.

Genuka WA aceptó mi solicitud, ¿por qué Meta la rechaza?

Genuka revisa la forma de la solicitud; Meta revisa además lo que solo ella conoce, como los parámetros propios de cada endpoint o el estado de la cuenta. El traceId que se transmite en meta es lo que pide el soporte de Meta.

Fuentes

En esta página