Errori dell'API v2

Ogni errore dell'API v2 arriva con un vero codice di stato HTTP e la stessa struttura JSON. Questa pagina elenca ogni code, cosa significa e cosa fare. Ogni risposta di errore rimanda al suo codice in questa pagina tramite docs.

L'oggetto errore#

{
  "error": {
    "code": "not_cancellable",
    "message": "Only a waiting message can be cancelled.",
    "field": null,
    "docs": "https://wbiztool.com/docs/api/v2/errors/#not_cancellable",
    "request_id": "req_4f1c2a9b8e7d6c5b4a392817",
    "status": "sent"
  }
}

Alcuni codici aggiungono dettagli propri, come status, count, used o limit; sono indicati insieme al codice. Una risposta con HTTP 401 ha anche un header WWW-Authenticate: Bearer realm="wbiztool", e le risposte con 429 (e il 409 idempotency_in_progress) hanno Retry-After.

In breve: 4xx significa che la richiesta va modificata (oppure, per 409 e 429, che bisogna aspettare); ripeterla invariata dà la stessa risposta. 5xx indica un problema da parte nostra; riprova più tardi, con lo stesso Idempotency-Key.

Autenticazione e limiti#

api_v2_not_enabled#

HTTP 403. L'API v2 non è disponibile per questo spazio di lavoro. Se vedi questo errore, contattaci.

Cosa fare: per ora continua a usare l'API v1. La scheda Chiavi API v2 in Impostazioni → Chiavi API mostra quando è disponibile per te.

missing_api_key#

HTTP 401. La richiesta non ha l'header Authorization: Bearer …, oppure è vuoto o usa un altro schema.

Cosa fare: invia Authorization: Bearer wbz_live_… (o wbz_test_…) in ogni richiesta. Vedi Chiavi.

invalid_api_key#

HTTP 401. La chiave non è una chiave v2 di WbizTool: digitata male, troncata o non creata da noi.

Cosa fare: copia di nuovo la chiave, senza spazi né virgolette. Una chiave non può essere mostrata di nuovo dopo la creazione; se l'hai persa, creane una nuova in Impostazioni → Chiavi API.

v1_key_on_v2#

HTTP 401. La chiave è una chiave dell'API v1 (40 caratteri, cifre e lettere da a a f). Le chiavi v1 funzionano solo su /api/v1/.

Cosa fare: crea una chiave v2 nella scheda Chiavi API v2 in Impostazioni → Chiavi API, oppure chiama l'API v1.

api_key_revoked#

HTTP 401. La chiave è stata revocata in Impostazioni → Chiavi API, oppure il suo spazio di lavoro è stato eliminato o disattivato.

Cosa fare: usa un'altra chiave, oppure chiedi a un Proprietario dello spazio di lavoro di crearne una nuova.

api_key_expired#

HTTP 401. La data di scadenza della chiave è passata.

Cosa fare: chiedi a un Proprietario dello spazio di lavoro di creare una nuova chiave e sostituisci quella vecchia nella tua app.

too_many_auth_failures#

HTTP 429. Più di 30 richieste in un minuto dal tuo indirizzo IP avevano una chiave errata. Retry-After è 60.

Cosa fare: fermati e correggi la chiave nella tua app, poi riprova dopo un minuto.

demo_account#

HTTP 403. Uno spazio di lavoro demo non può usare l'API.

Cosa fare: registrati con un tuo account e crea lì una chiave.

missing_scope#

HTTP 403. La chiave non ha lo scope di cui questa richiesta ha bisogno. required_scope nell'errore indica quale, ad esempio messages:send.

Cosa fare: crea una chiave con quello scope (non si possono aggiungere scope a una chiave esistente). Vedi Scope.

rate_limited#

HTTP 429. La chiave ha fatto più di 60 richieste in questo minuto, o più di 10.000 oggi (UTC).

Cosa fare: aspetta il numero di secondi indicato in Retry-After, poi riprova. Distribuisci le richieste nel tempo, usa POST /messages/batch per molti destinatari e i webhook invece del polling. Vedi Limiti di richieste.

Richiesta#

not_found#

HTTP 404. A questo indirizzo non c'è nulla: il percorso è digitato male, oppure non è un percorso dell'API v2.

Cosa fare: confronta il percorso con la documentazione di riferimento, ad esempio /api/v2/messages, non /api/v2/message.

invalid_json#

HTTP 400. Il body non è JSON valido, spesso a causa di una virgola finale o di un a capo non codificato in text.

Cosa fare: controlla il JSON e scrivi gli a capo nelle stringhe come \n. Lascia che sia la tua libreria HTTP a costruire il body (json= in Python requests, JSON.stringify in JavaScript).

unsupported_content_type#

HTTP 415. Il body non è inviato nel formato che questo endpoint accetta: ogni endpoint accetta application/json, tranne POST /media, che accetta multipart/form-data.

Cosa fare: imposta Content-Type: application/json e invia JSON, oppure invia il caricamento come multipart con il campo file.

method_not_allowed#

HTTP 405. Il percorso esiste, ma non con questo metodo, ad esempio PUT /messages/9817263.

Cosa fare: usa il metodo indicato nella documentazione di riferimento. Per modificare un promemoria si usa PATCH; per annullare un messaggio DELETE.

request_too_large#

HTTP 413. Il body della richiesta è troppo grande.

Cosa fare: invia meno dati in una richiesta, ad esempio dividendo un lungo elenco in più batch.

validation_failed#

HTTP 400. La richiesta non ha la struttura giusta: manca un campo obbligatorio, un valore ha il tipo sbagliato o è troppo lungo, un campo non è riconosciuto, oppure limit non è compreso tra 1 e 100. field indica il primo problema e message lo spiega; errors elenca gli altri.

Cosa fare: correggi il campo indicato in field. I nomi dei campi sono in snake_case e i campi sconosciuti vengono rifiutati, quindi controlla errori di battitura come txt o phone_number.

invalid_cursor#

HTTP 400. Il cursor è danneggiato, oppure è stato creato per filtri diversi da quelli di questa richiesta.

Cosa fare: invia esattamente il next_cursor ricevuto, con gli stessi filtri della prima pagina. Per cambiare i filtri, ricomincia senza cursore.

invalid_idempotency_key#

HTTP 400. L'header Idempotency-Key è vuoto, supera i 255 caratteri o contiene caratteri non stampabili.

Cosa fare: usa un UUID o un'altra stringa breve di lettere, cifre e trattini.

idempotency_key_reused#

HTTP 422. Questo Idempotency-Key è già stato usato nelle ultime 24 ore con una richiesta diversa: un altro metodo, percorso o body.

Cosa fare: usa una nuova chiave per ogni nuova richiesta e riutilizza una chiave solo per ripetere esattamente la stessa richiesta. Vedi Idempotency-Key.

idempotency_in_progress#

HTTP 409. La prima richiesta con questo Idempotency-Key è ancora in elaborazione. Retry-After è 1.

Cosa fare: aspetta un secondo e invia di nuovo la stessa richiesta: riceverai la risposta della prima richiesta.

internal_error#

HTTP 500. Qualcosa è andato storto da parte nostra. Ne veniamo avvisati.

Cosa fare: riprova più tardi con lo stesso Idempotency-Key, così l'operazione non viene eseguita due volte. Se continua a succedere, contattaci indicando il request_id.

Messaggi#

text_required#

HTTP 400. Il messaggio non ha né text né media, oppure il testo contiene solo spazi. Per un promemoria, text è obbligatorio.

Cosa fare: invia text, media o entrambi.

text_too_long#

HTTP 400. text supera i 3.000 caratteri.

Cosa fare: accorcialo, oppure dividilo in più messaggi.

too_many_recipients#

HTTP 400. Un batch ha più di 1.000 destinatari in to.

Cosa fare: dividi l'elenco in batch di massimo 1.000, ognuno con il proprio Idempotency-Key.

invalid_datetime#

HTTP 400. Un orario (send_at, expires_at, since, until) non è in formato ISO 8601 con il suo offset.

Cosa fare: scrivilo come 2026-10-20T09:30:00+05:30 o 2026-10-20T04:00:00Z. Un orario senza offset, come 2026-10-20 09:30, viene rifiutato perché è ambiguo. In una query string, scrivi + come %2B.

invalid_phone#

HTTP 422. Un numero di telefono (to.phone, oppure phone quando colleghi un numero) non è un numero valido in formato internazionale con +.

Cosa fare: scrivilo con + e il prefisso internazionale, come +919876543210. Spazi e trattini vanno bene; uno 0 iniziale al posto del prefisso internazionale no.

invalid_username#

HTTP 422. to.username non è un username di Telegram.

Cosa fare: scrivi @name, un link t.me/name oppure tg: seguito da un id utente. Vedi Destinatari.

username_needs_telegram#

HTTP 422. Si può inviare a un username di Telegram solo da un account Telegram, e from è un numero WhatsApp (oppure, senza from, non c'è esattamente un account Telegram collegato).

Cosa fare: imposta from sull'id di un account Telegram, oppure invia a un numero di telefono.

contact_not_found#

HTTP 422. Nello spazio di lavoro non c'è nessun contatto con questo to.contact_id.

Cosa fare: controlla l'id (ad esempio il contact_id di un messaggio precedente), oppure invia a to.phone.

media_not_found#

HTTP 422 quando invii un messaggio o crei un promemoria con media.media_id; HTTP 404 per GET o DELETE /media/{id}. Nella Directory media dello spazio di lavoro non c'è nessun file con questo id, oppure è stato eliminato.

Cosa fare: controlla l'id con Elencare i file, oppure carica di nuovo il file.

invalid_media_url#

HTTP 422. media.url non è un link pubblico http o https: è malformato, oppure punta a un indirizzo privato o locale.

Cosa fare: usa un link che chiunque su internet possa aprire, oppure carica il file e invialo tramite media_id.

time_in_past#

HTTP 422. send_at o expires_at è già passato.

Cosa fare: controlla l'orario e il suo offset. Per inviare subito, ometti send_at.

number_not_found#

HTTP 422 quando from (o number_id durante il collegamento) non è un numero di questo spazio di lavoro; HTTP 404 per GET /numbers/{id}, anche quando la chiave non può usare quel numero.

Cosa fare: ottieni l'id corretto con Elencare i numeri.

from_required#

HTTP 422. Manca from, e lo spazio di lavoro non ha nessun numero collegato oppure ne ha più di uno, quindi non è chiaro quale debba inviare. (Per una chiave limitata ad alcuni numeri: l'unico numero collegato non è tra i suoi numeri.)

Cosa fare: invia from con l'id del numero da cui inviare.

number_not_allowed#

HTTP 403. La chiave è limitata ad alcuni numeri e questa richiesta ne richiede un altro: from è un altro numero, un promemoria non indica uno dei suoi numeri, una richiesta di collegamento aggiunge un numero o ne indica un altro, oppure la richiesta gestisce endpoint dei webhook.

Cosa fare: usa uno dei numeri della chiave (number_ids in GET /me), oppure una chiave non limitata.

no_credits#

HTTP 402. Lo spazio di lavoro non ha più messaggi disponibili nel suo piano. Per un batch, requested e remaining indicano quanti ne sono stati richiesti e quanti ne restano.

Cosa fare: invia meno messaggi, oppure acquista un piano o altri messaggi; i piani a pagamento inviano messaggi illimitati. Vedi Quando finiscono i messaggi.

account_disabled#

HTTP 403. L'account del proprietario dello spazio di lavoro è disattivato, quindi lo spazio di lavoro non può inviare.

Cosa fare: contatta l'assistenza.

number_daily_cap_reached#

HTTP 429. Il numero mittente ha inviato 1.000 messaggi nelle ultime 24 ore (uso corretto), oppure un batch non rientrerebbe in ciò che resta: requested e room indicano quanti.

Cosa fare: invia il resto più tardi, oppure da un altro numero.

message_rejected#

HTTP 422. Non è stato possibile mettere il messaggio in coda; message spiega perché. Non è stato salvato nulla.

Cosa fare: correggi ciò che descrive message e invia di nuovo.

message_not_found#

HTTP 404. Nessun messaggio con questo id per questa chiave: non esiste, appartiene a un altro spazio di lavoro, oppure è stato inviato da un numero che la chiave non può usare. Una chiave di test vede solo i propri messaggi di test, e una chiave live non li vede mai.

Cosa fare: controlla l'id, e che tu stia usando lo stesso tipo di chiave (live o test) che ha creato il messaggio.

not_cancellable#

HTTP 409. Si può annullare solo un messaggio in attesa (queued o scheduled), e questo non è più in attesa. status nell'errore indica il suo stato attuale, ad esempio sent o cancelled.

Cosa fare: non c'è nulla da annullare. Un messaggio già inviato non può essere richiamato.

Promemoria#

invalid_cron#

HTTP 400. schedule.cron non è un'espressione cron di 5 parti, oppure descrive un momento che non arriva mai (come il 31 febbraio).

Cosa fare: scrivi minuto, ora, giorno del mese, mese e giorno della settimana, ad esempio 0 9 * * 1 per il lunedì alle 09:00. Vedi Pianificazione.

invalid_timezone#

HTTP 400. schedule.timezone non è un nome di fuso orario IANA.

Cosa fare: usa un nome come Asia/Kolkata, Europe/London o America/New_York, non un'abbreviazione come IST o un offset come +05:30. Vedi il riferimento dei fusi orari.

number_not_connected#

HTTP 422. Il from del promemoria non è un numero collegato di questo spazio di lavoro.

Cosa fare: collega prima il numero, scegline uno collegato, oppure ometti from (null) così che lo invii un qualsiasi numero collegato.

reminder_not_found#

HTTP 404. Nessun promemoria con questo id: non esiste, è stato eliminato, oppure invia da un numero che la chiave non può usare.

Cosa fare: controlla l'id con Elencare i promemoria.

File multimediali#

file_too_large#

HTTP 413. Il file caricato supera i 64 MB.

Cosa fare: comprimilo o dividilo; per un video, riducine la risoluzione.

unsupported_file_type#

HTTP 415. Il tipo di file non può essere inviato su WhatsApp. Il tipo viene letto dall'estensione alla fine del nome del file.

Cosa fare: controlla i tipi che puoi caricare e mantieni l'estensione nel nome (price-list.pdf, non price-list).

storage_full#

HTTP 422. Il file non entra nella Directory media dello spazio di lavoro per il suo piano. used e limit indicano lo spazio usato e quello consentito, in byte.

Cosa fare: elimina i file che non ti servono più, oppure passa a un piano con più spazio di archiviazione.

media_in_use#

HTTP 409. Il file non può ancora essere eliminato: qualcosa lo invierà ancora (un messaggio in attesa, anche di una campagna, un promemoria attivo o un trigger di Google Sheets attivo). count indica quanti.

Cosa fare: annulla o modifica prima questi elementi, oppure aspetta che i messaggi in attesa siano partiti.

upload_failed#

HTTP 502. Non è stato possibile salvare il file da parte nostra.

Cosa fare: riprova, con lo stesso Idempotency-Key.

Verifiche dei numeri#

no_valid_numbers#

HTTP 422. Nessuna delle voci in numbers è un numero di telefono. skipped indica quante voci c'erano.

Cosa fare: invia i numeri in formato internazionale con +, uno per voce, come +919876543210.

too_many_numbers#

HTTP 422. La verifica contiene più numeri di quanti ne possa avere una verifica: oltre 10.000 voci nella richiesta, oppure più numeri di quanti il piano ne consenta per verifica. count e limit indicano quanti.

Cosa fare: dividi l'elenco in più verifiche. Vedi Limiti del piano.

number_check_quota_reached#

HTTP 422. La verifica supererebbe le verifiche dei numeri del piano per questo periodo di fatturazione. requested, used e limit indicano quante.

Cosa fare: verifica meno numeri, aspetta il prossimo periodo di fatturazione oppure passa a un piano superiore.

number_check_not_found#

HTTP 404. Nello spazio di lavoro non c'è nessuna verifica dei numeri con questo id.

Cosa fare: controlla l'id con Elencare le verifiche.

Numeri#

plan_required#

HTTP 403. Il piano dello spazio di lavoro non include ciò di cui questa richiesta ha bisogno: l'API del codice QR per collegare un numero, i promemoria per creare, modificare o riprendere un promemoria, oppure la verifica dei numeri per avviare una verifica dei numeri.

Cosa fare: un Proprietario può passare a un piano superiore in Prezzi. Leggere ciò che esiste già funziona con qualsiasi piano.

number_limit_reached#

HTTP 403. Il piano non ha spazio per un altro numero.

Cosa fare: ricollega un numero esistente con number_id, rimuovi un numero che non usi più oppure passa a un piano superiore.

already_connected#

HTTP 409. Il numero è già collegato.

Cosa fare: non c'è nulla da fare: puoi inviare da quel numero. Controlla con Ottenere un numero.

connect_in_progress#

HTTP 409. Questo numero è in fase di collegamento proprio ora. number_id nell'errore indica quale.

Cosa fare: interroga GET /numbers/{id} per quel numero invece di richiederlo di nuovo. Dopo 10 minuti senza scansione, puoi richiederlo di nuovo.

Webhook#

invalid_webhook_url#

HTTP 422. url non è un indirizzo pubblico https://: è http://, malformato, oppure punta a un indirizzo privato o locale.

Cosa fare: usa un indirizzo https:// a cui il tuo server risponde da internet. Per fare test sul tuo computer, usa un servizio di tunnel che ti fornisca un indirizzo pubblico https://.

webhook_limit_reached#

HTTP 403. Lo spazio di lavoro ha già 5 endpoint dei webhook.

Cosa fare: rimuovine uno che non usi più. Un solo endpoint può ricevere tutti i tipi di evento.

webhook_not_found#

HTTP 404. Nessun endpoint del webhook con questo id: non esiste oppure è stato rimosso. Anche testare o ruotare il secret di un endpoint disattivato dà questa risposta; leggendolo vedi active: false.

Cosa fare: controlla l'id con Elencare gli endpoint. Se è stato disattivato, aggiungilo di nuovo.

Modalità test#

test_mode_unsupported#

HTTP 403. Una chiave di test (wbz_test_…) può inviare, leggere e annullare messaggi di test e leggere il resto dello spazio di lavoro, ma non modificare nient'altro: collegare un numero, creare, modificare o eliminare promemoria, caricare o eliminare file multimediali, avviare una verifica dei numeri o gestire endpoint dei webhook. Anche il filtro status di GET /messages non è supportato per le chiavi di test.

Cosa fare: usa una chiave live (wbz_live_…) per queste richieste. Vedi Modalità test.