# Errore WhatsApp 100: Invalid parameter — causa e soluzione

URL: https://wa.genuka.com/it/docs/errors/100
Language: Italian

> 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](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#other-errors)

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?

| Situazione                                                                                         | Cosa restituisce Meta                                                                                                                                                                 | Fonte                                                                                                                                                               |
| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Parametro sconosciuto o scritto male                                                               | `(#100) Invalid parameter`, con il parametro incriminato in `details`                                                                                                                 | Meta                                                                                                                                                                |
| Valore oltre un limite di lunghezza                                                                | Stesso codice                                                                                                                                                                         | Meta                                                                                                                                                                |
| Chiave pubblica dei Flows che non è una chiave RSA a 2048 bit in PEM                               | Stesso codice                                                                                                                                                                         | Meta                                                                                                                                                                |
| Messaggio non basato su modello inviato alla Marketing Messages API                                | `details`: "Message must be a template message."                                                                                                                                      | [Meta](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#marketing-messages-api-for-whatsapp-error-codes)               |
| ID del numero di telefono o dell'account sbagliato, oppure un token senza accesso a quella risorsa | `error_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 `details` | Segnalazioni di sviluppatori: [Activepieces](https://community.activepieces.com/t/whatsapp-business-error/4324), [Fast2SMS](https://www.fast2sms.com/help/?p=17132) |
| Invio da un numero a se stesso                                                                     | `(#100) Invalid parameter`, senza alcun dettaglio                                                                                                                                     | Osservazione di Genuka                                                                                                                                              |
| Eliminazione di un modello senza diritti sull'account WhatsApp                                     | `(#100) Need permission on either WhatsApp Business Account or owner/shared business`                                                                                                 | Osservazione 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 Genuka                                                      | Risposta                                                       |
| ------------------------------------------------------------------------ | -------------------------------------------------------------- |
| Messaggio senza campo di contenuto, media senza `assetId`, `id` o `link` | `400 missing_content`, `400 invalid_media`                     |
| Modello con componenti malformati                                        | `400 invalid_template` (disattivabile con `"validate": false`) |
| `to` uguale al numero mittente                                           | `400 recipient_is_sender`                                      |

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

```json title="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](https://wa.genuka.com/it/docs/messages)).

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](https://www.fast2sms.com/help/?p=17132)). Con
Genuka WA, leggi `GET /api/v1/connections`: un numero il cui stato non è più `connected` rientra
nella pagina dell'[errore 200](https://wa.genuka.com/it/docs/errors/200); un numero eliminato dal lato di Meta, nella
pagina dell'[errore 33](https://wa.genuka.com/it/docs/errors/33).

## Come risolvo l'errore 100?

1. **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`.
2. **Confronta la richiesta con il riferimento.** Per gli invii, il [riferimento API](https://wa.genuka.com/it/docs/api#messaggi) e
   [Inviare messaggi](https://wa.genuka.com/it/docs/messages) 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.
3. **Togli ciò che hai aggiunto "per sicurezza".** Un campo della Cloud API copiato in `raw` ma
   sconosciuto all'endpoint basta a provocare un `100`.
4. **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`.

**Node.js**

```ts
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"),
  });
}
```

**Python**

```python
import os
import requests

response = requests.post(
    "https://wa.genuka.com/api/v1/messages",
    headers={"Authorization": f"Bearer {os.environ['GENUKA_WA_API_KEY']}"},
    json={"connectionId": "con_1", "to": "+237690000001", "text": "Il tuo pacco è in viaggio."},
    timeout=30,
)
if not response.ok:
    body = response.json()
    meta = body.get("meta") or {}
    print({
        "status": response.status_code,
        "error": body.get("error"),
        "meta_code": meta.get("code"),
        "details": meta.get("details") or body.get("message"),
        "trace_id": meta.get("traceId"),
        "request_id": response.headers.get("x-request-id"),
    })
```

**PHP**

```php
<?php
$ch = curl_init("https://wa.genuka.com/api/v1/messages");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERAGENT => "acme-crm/1.0 (+https://example.com)",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("GENUKA_WA_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "connectionId" => "con_1",
        "to" => "+237690000001",
        "text" => "Il tuo pacco è in viaggio.",
    ]),
]);
$body = json_decode(curl_exec($ch), true);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

if ($status >= 400) {
    error_log(json_encode([
        "status" => $status,
        "error" => $body["error"] ?? null,
        "meta_code" => $body["meta"]["code"] ?? null,
        "details" => $body["meta"]["details"] ?? ($body["message"] ?? null),
        "trace_id" => $body["meta"]["traceId"] ?? null,
    ]));
}
```

**curl**

```bash
curl -s -X POST https://wa.genuka.com/api/v1/messages \
  -H "Authorization: Bearer $GENUKA_WA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectionId": "con_1", "to": "+237690000001", "text": "Il tuo pacco è in viaggio." }' \
  | jq '{error, code: .meta.code, details: .meta.details, traceId: .meta.traceId}'
```

## 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](https://wa.genuka.com/it/docs/errors/132000): il numero di variabili inviate non corrisponde al modello.
* [33](https://wa.genuka.com/it/docs/errors/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](https://wa.genuka.com/it/docs/errors/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

* [Meta — Error codes](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes)
* [Meta — Error codes, Marketing Messages API for WhatsApp](https://developers.facebook.com/documentation/business-messaging/whatsapp/support/error-codes#marketing-messages-api-for-whatsapp-error-codes)
* [Community Activepieces — codice 100, error\_subcode 33](https://community.activepieces.com/t/whatsapp-business-error/4324)
* [Fast2SMS — Unsupported POST/GET request, object does not exist](https://www.fast2sms.com/help/?p=17132)
