Genuka WA docs

Errore WhatsApp 100: Invalid parameter — causa e soluzione

Errore 100 della WhatsApp Cloud API (Invalid parameter): un parametro sconosciuto, scritto male o troppo lungo. Come leggere details e correggere la richiesta.

L'errore WhatsApp 100 significa che la tua richiesta alla Cloud API contiene un parametro che Meta non riconosce, uno scritto male, oppure un valore che supera un limite di lunghezza. Di solito è un errore di contenuto: inviare di nuovo la stessa richiesta fallirà sempre. La causa è generalmente indicata nel campo details; con il sottocodice 33, a essere sbagliato è l'ID a cui punti.

Cosa significa l'errore 100?

Meta lo classifica tra gli "altri errori" della Cloud API:

"The request included one or more unsupported or misspelled parameters." — Meta, Cloud API error codes

La soluzione suggerita da Meta elenca quattro verifiche: leggere il riferimento dell'endpoint per i parametri supportati e la loro ortografia; per i WhatsApp Flows con un endpoint, fornire una chiave pubblica RSA valida a 2048 bit in formato PEM; assicurarsi che il phone_number_id che registri corrisponda a quello memorizzato in precedenza; e restare sotto i limiti di lunghezza di ciascun tipo.

Nella risposta della Graph API, message è spesso (#100) Invalid parameter, un titolo generico. L'informazione utile è altrove: Meta descrive details come il campo che può dire "which parameter is invalid or what values are acceptable" (stessa pagina).

Quando si verifica l'errore 100?

SituazioneCosa restituisce MetaFonte
Parametro sconosciuto o scritto male(#100) Invalid parameter, con il parametro incriminato in detailsMeta
Valore oltre un limite di lunghezzaStesso codiceMeta
Chiave pubblica dei Flows che non è una chiave RSA a 2048 bit in PEMStesso codiceMeta
Messaggio non basato su modello inviato alla Marketing Messages APIdetails: "Message must be a template message."Meta
ID del numero di telefono o dell'account sbagliato, oppure un token senza accesso a quella risorsaerror_subcode: 33 e "Unsupported post request. Object with ID '…' does not exist, cannot be loaded due to missing permissions, or does not support this operation", senza detailsSegnalazioni di sviluppatori: Activepieces, Fast2SMS
Invio da un numero a se stesso(#100) Invalid parameter, senza alcun dettaglioOsservazione di Genuka
Eliminazione di un modello senza diritti sull'account WhatsApp(#100) Need permission on either WhatsApp Business Account or owner/shared businessOsservazione di Genuka

Le ultime due righe vengono dalle nostre chiamate. Per un invio a se stessi, Meta documenta in realtà un codice dedicato, 131021 ("Sender and recipient phone number is the same"), ma quello che abbiamo ricevuto era un semplice 100.

Dove lo vedi in Genuka WA?

Genuka WA convalida buona parte della richiesta prima di Meta, e in quel caso risponde senza che Meta veda nulla:

Controllo di GenukaRisposta
Messaggio senza campo di contenuto, media senza assetId, id o link400 missing_content, 400 invalid_media
Modello con componenti malformati400 invalid_template (disattivabile con "validate": false)
to uguale al numero mittente400 recipient_is_sender

Quando il rifiuto viene da Meta, Genuka riporta il codice 100 senza riclassificarlo: la classe è unknown, non ritentabile.

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…"
  }
}

Su POST /api/v1/templates, lo stesso rifiuto torna come 422 meta_rejected con lo stesso oggetto meta. Il campo raw di POST /api/v1/messages non viene mai convalidato da Genuka: gli errori tornano direttamente da Meta (Inviare messaggi).

In una campagna MARKETING, un 100 dalla Marketing Messages API fa sì che Genuka invii di nuovo il messaggio tramite l'endpoint /messages standard; se rifiuta anche quello, il destinatario passa a failed.

E il sottocodice 33?

Non è un errore di contenuto. Con meta.code: 100 e meta.subcode: 33, e un messaggio che inizia con "Unsupported post request" (o "get" per una lettura), la Graph API sta dicendo che l'oggetto di destinazione non esiste, oppure che il token non vi ha accesso. Le cause segnalate sono un ID del numero di telefono o dell'account WhatsApp sbagliato, un token che ha perso l'accesso a quella risorsa, oppure un accesso partner rimosso (Fast2SMS). Con Genuka WA, leggi GET /api/v1/connections: un numero il cui stato non è più connected rientra nella pagina dell'errore 200; un numero eliminato dal lato di Meta, nella pagina dell'errore 33.

Come risolvo l'errore 100?

Leggi meta.details. È l'unica parte della risposta che nomina il problema. Registralo nei log insieme a meta.traceId e all'header x-request-id.

Confronta la richiesta con il riferimento. Per gli invii, il riferimento API e Inviare messaggi elencano ogni campo accettato e i suoi limiti: 4.096 caratteri per un testo, 1.024 per la didascalia di un'immagine, 20 per il titolo di un pulsante, al massimo 3 pulsanti di risposta.

Togli ciò che hai aggiunto "per sicurezza". Un campo della Cloud API copiato in raw ma sconosciuto all'endpoint basta a provocare un 100.

Se details è vuoto, riduci la richiesta. Invia lo stesso messaggio ridotto all'osso (un semplice text allo stesso numero), poi aggiungi di nuovo gli elementi uno alla volta. Se fallisce anche un messaggio minimo, controlla che to non sia il numero mittente e contatta il supporto Genuka con x-request-id e 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: "Il tuo pacco è in viaggio." }),
});
const json = await response.json();

if (!response.ok) {
  // Tutto ciò che serve per la diagnosi, senza inviare di nuovo la richiesta.
  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"),
  });
}

Come prevengo l'errore 100?

  • Lascia attiva la convalida di Genuka. Su POST /api/v1/templates, passa "validate": false solo per un componente che Meta accetta e che il nostro validatore rifiuta.
  • Preferisci i campi tipizzati a raw. La forma dei campi tipizzati viene controllata prima dell'invio (campi obbligatori, media senza id o link); i limiti di lunghezza e di numero restano applicati da Meta, e raw non viene controllato affatto.
  • Testa ogni nuovo tipo di messaggio su un numero di test prima di inserirlo in un invio di massa: un 100 è lo stesso per tutti i destinatari.

Codici di errore correlati

  • 131008: manca un parametro obbligatorio.
  • 131009: il parametro esiste, ma il suo valore non è valido.
  • 131021: mittente e destinatario sono lo stesso numero.
  • 132000: il numero di variabili inviate non corrisponde al modello.
  • 33: numero eliminato (codice 33), da non confondere con il sottocodice 33 del codice 100, che segnala un oggetto che non si trova o a cui non si ha accesso (numero eliminato o accesso perso).
  • 200: l'accesso all'account WhatsApp è stato rimosso, oppure manca un'autorizzazione.

FAQ

Perché details a volte è vuoto?

Meta non lo compila sempre. Un invio da un numero a se stesso, per esempio, torna come (#100) Invalid parameter e nient'altro, ed è per questo che Genuka WA lo controlla prima.

Devo riprovare una richiesta rifiutata con 100?

No. Il problema è il contenuto, oppure l'ID di destinazione con il sottocodice 33: la stessa richiesta produrrà lo stesso errore. Correggila prima.

Qual è la differenza tra l'errore 100 e l'errore 131009?

Meta descrive il 100 come un parametro non supportato o scritto male, e il 131009 come un parametro noto il cui valore non è valido. Entrambi si risolvono leggendo details.

Genuka WA ha accettato la mia richiesta, perché allora Meta la rifiuta?

Genuka controlla la forma della richiesta; Meta controlla anche ciò che solo lei sa, come i parametri specifici dell'endpoint o lo stato dell'account. Il traceId riportato in meta è quello che chiede il supporto Meta.

Fonti

In questa pagina