Errores de la API v2

Cada error de la API v2 llega con un código de estado HTTP real y la misma forma JSON. Esta página recoge cada code, qué significa y qué hacer. Cada respuesta de error enlaza a su código en esta página en docs.

El objeto de error#

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

Algunos códigos añaden datos propios, como status, count, used o limit; se indican junto al código. Una respuesta con HTTP 401 también lleva una cabecera WWW-Authenticate: Bearer realm="wbiztool", y las respuestas con 429 (y el 409 idempotency_in_progress) llevan Retry-After.

En resumen: 4xx significa que hay que cambiar la solicitud (o, con 409 y 429, esperar); repetirla sin cambios da la misma respuesta. 5xx significa que el problema es nuestro; vuelve a intentarlo más tarde, con la misma Idempotency-Key.

Autenticación y límites#

api_v2_not_enabled#

HTTP 403. La API v2 no está disponible para este espacio de trabajo. Si ves esto, contáctanos.

Qué hacer: sigue usando la API v1 por ahora. La tarjeta Claves API v2 de Configuración → Claves API muestra cuándo está abierta para ti.

missing_api_key#

HTTP 401. La solicitud no tiene cabecera Authorization: Bearer …, o está vacía o usa otro esquema.

Qué hacer: envía Authorization: Bearer wbz_live_… (o wbz_test_…) en cada solicitud. Consulta Claves.

invalid_api_key#

HTTP 401. La clave no es una clave v2 de WbizTool: está mal escrita, cortada o no la creamos nosotros.

Qué hacer: vuelve a copiar la clave, sin espacios ni comillas. Una clave no se puede volver a mostrar después de crearla; si la has perdido, crea una nueva en Configuración → Claves API.

v1_key_on_v2#

HTTP 401. La clave es una clave de la API v1 (40 caracteres, dígitos y de a a f). Las claves v1 solo funcionan en /api/v1/.

Qué hacer: crea una clave v2 en la tarjeta Claves API v2 de Configuración → Claves API, o llama a la API v1.

api_key_revoked#

HTTP 401. La clave se revocó en Configuración → Claves API, o su espacio de trabajo se eliminó o se desactivó.

Qué hacer: usa otra clave o pide a un Propietario del espacio de trabajo que cree una nueva.

api_key_expired#

HTTP 401. Ya pasó la fecha de caducidad de la clave.

Qué hacer: pide a un Propietario del espacio de trabajo que cree una clave nueva y reemplaza la anterior en tu app.

too_many_auth_failures#

HTTP 429. Más de 30 solicitudes en un minuto desde tu dirección IP llevaban una clave incorrecta. Retry-After es 60.

Qué hacer: detente y corrige la clave en tu app; luego vuelve a intentarlo pasado un minuto.

demo_account#

HTTP 403. Un espacio de trabajo de demostración no puede usar la API.

Qué hacer: regístrate para tener tu propia cuenta y crea allí una clave.

missing_scope#

HTTP 403. La clave no tiene el permiso que necesita esta solicitud. required_scope en el error dice cuál, como messages:send.

Qué hacer: crea una clave con ese permiso (no se pueden añadir permisos a una clave existente). Consulta Permisos.

rate_limited#

HTTP 429. La clave ha hecho más de 60 solicitudes en este minuto, o más de 10.000 hoy (UTC).

Qué hacer: espera los segundos que indica Retry-After y vuelve a intentarlo. Reparte las solicitudes, usa POST /messages/batch para muchos destinatarios y webhooks en lugar de consultar una y otra vez. Consulta Límites de solicitudes.

Solicitud#

not_found#

HTTP 404. No hay nada en esta dirección: la ruta está mal escrita o no es una ruta de la API v2.

Qué hacer: compara la ruta con la referencia, por ejemplo /api/v2/messages, no /api/v2/message.

invalid_json#

HTTP 400. El cuerpo no es JSON válido, a menudo por una coma final o un salto de línea sin escapar en text.

Qué hacer: revisa el JSON y escribe los saltos de línea dentro de las cadenas como \n. Deja que tu biblioteca HTTP construya el cuerpo (json= en Python requests, JSON.stringify en JavaScript).

unsupported_content_type#

HTTP 415. El cuerpo no se envía como lo acepta este endpoint: todos los endpoints aceptan application/json, excepto POST /media, que acepta multipart/form-data.

Qué hacer: pon Content-Type: application/json y envía JSON, o envía la subida como multipart con el campo file.

method_not_allowed#

HTTP 405. La ruta existe, pero no con este método, como PUT /messages/9817263.

Qué hacer: usa el método que indica la referencia. Un cambio en un recordatorio es PATCH; cancelar un mensaje es DELETE.

request_too_large#

HTTP 413. El cuerpo de la solicitud es demasiado grande.

Qué hacer: envía menos en una sola solicitud; por ejemplo, divide una lista larga en varios lotes.

validation_failed#

HTTP 400. La solicitud no tiene la forma correcta: falta un campo obligatorio, un valor tiene un tipo incorrecto o es demasiado largo, un campo no se conoce o limit no está entre 1 y 100. field nombra el primer problema y message lo explica; errors recoge los demás.

Qué hacer: corrige el campo que nombra field. Los nombres de campo están en snake_case y los campos desconocidos se rechazan, así que busca errores de escritura como txt o phone_number.

invalid_cursor#

HTTP 400. El cursor está dañado o se creó para otros filtros distintos de los de esta solicitud.

Qué hacer: envía exactamente el next_cursor que recibiste, con los mismos filtros que la primera página. Para cambiar los filtros, vuelve a empezar sin cursor.

invalid_idempotency_key#

HTTP 400. La cabecera Idempotency-Key está vacía, tiene más de 255 caracteres o contiene caracteres que no se pueden imprimir.

Qué hacer: usa un UUID u otra cadena corta de letras, dígitos y guiones.

idempotency_key_reused#

HTTP 422. Esta Idempotency-Key ya se usó en las últimas 24 horas con una solicitud distinta: otro método, otra ruta u otro cuerpo.

Qué hacer: usa una clave nueva para cada solicitud nueva, y reutiliza una clave solo para repetir exactamente la misma solicitud. Consulta Idempotency-Key.

idempotency_in_progress#

HTTP 409. La primera solicitud con esta Idempotency-Key todavía se está procesando. Retry-After es 1.

Qué hacer: espera un segundo y vuelve a enviar la misma solicitud: recibirás la respuesta de la primera.

internal_error#

HTTP 500. Algo salió mal por nuestra parte. Se nos avisa de ello.

Qué hacer: vuelve a intentarlo más tarde con la misma Idempotency-Key, para que el trabajo no se haga dos veces. Si sigue pasando, contáctanos con el request_id.

Mensajes#

text_required#

HTTP 400. El mensaje no tiene text ni media, o el texto solo tiene espacios. En un recordatorio, text es obligatorio.

Qué hacer: envía text, media o ambos.

text_too_long#

HTTP 400. text tiene más de 3.000 caracteres.

Qué hacer: acórtalo o divídelo en varios mensajes.

too_many_recipients#

HTTP 400. Un lote tiene más de 1.000 destinatarios en to.

Qué hacer: divide la lista en lotes de hasta 1.000, cada uno con su propia Idempotency-Key.

invalid_datetime#

HTTP 400. Una hora (send_at, expires_at, since, until) no está en ISO 8601 con su desfase.

Qué hacer: escríbela como 2026-10-20T09:30:00+05:30 o 2026-10-20T04:00:00Z. Una hora sin desfase, como 2026-10-20 09:30, se rechaza porque es ambigua. En una query string, escribe + como %2B.

invalid_phone#

HTTP 422. Un número de teléfono (to.phone, o phone al conectar un número) no es un número válido en formato internacional con +.

Qué hacer: escríbelo con + y el código de país, como +919876543210. Los espacios y los guiones no son problema; un 0 inicial en lugar del código de país, sí.

invalid_username#

HTTP 422. to.username no es un nombre de usuario de Telegram.

Qué hacer: escribe @name, un enlace t.me/name o tg: y un id de usuario. Consulta Destinatarios.

username_needs_telegram#

HTTP 422. Solo se puede enviar a un nombre de usuario de Telegram desde una cuenta de Telegram, y from es un número de WhatsApp (o, sin from, no hay exactamente una cuenta de Telegram conectada).

Qué hacer: pon en from el id de una cuenta de Telegram, o envía a un número de teléfono.

contact_not_found#

HTTP 422. No hay ningún contacto con este to.contact_id en el espacio de trabajo.

Qué hacer: comprueba el id (el contact_id de un mensaje anterior, por ejemplo) o envía a to.phone.

media_not_found#

HTTP 422 al enviar un mensaje o crear un recordatorio con media.media_id; HTTP 404 con GET o DELETE /media/{id}. No hay ningún archivo con este id en el Directorio de medios del espacio de trabajo, o se eliminó.

Qué hacer: comprueba el id con Listar archivos o vuelve a subir el archivo.

invalid_media_url#

HTTP 422. media.url no es un enlace público http o https: está mal formado o apunta a una dirección privada o local.

Qué hacer: usa un enlace que cualquiera pueda abrir en internet, o sube el archivo y envíalo con media_id.

time_in_past#

HTTP 422. send_at o expires_at ya pasó.

Qué hacer: revisa la hora y su desfase. Para enviar ahora, omite send_at.

number_not_found#

HTTP 422 cuando from (o number_id al conectar) no es un número de este espacio de trabajo; HTTP 404 con GET /numbers/{id}, también cuando la clave no puede usar ese número.

Qué hacer: obtén el id correcto con Listar números.

from_required#

HTTP 422. Falta from y el espacio de trabajo no tiene ningún número conectado o tiene más de uno, así que no está claro cuál debe enviar. (Con una clave limitada a algunos números: el único número conectado no es uno de sus números).

Qué hacer: envía from con el id del número desde el que se envía.

number_not_allowed#

HTTP 403. La clave está limitada a algunos números y esta solicitud necesita otro: from es otro número, un recordatorio no indica uno de sus números, una solicitud de conexión añade un número o indica otro, o la solicitud gestiona endpoints de webhook.

Qué hacer: usa uno de los números de la clave (number_ids en GET /me) o una clave que no esté limitada.

no_credits#

HTTP 402. Al espacio de trabajo no le quedan mensajes en su plan. En un lote, requested y remaining dicen cuántos se pidieron y cuántos quedan.

Qué hacer: envía menos mensajes, o compra un plan o más mensajes; los planes de pago envían mensajes ilimitados. Consulta Cuando te quedas sin mensajes.

account_disabled#

HTTP 403. La cuenta del propietario del espacio de trabajo está desactivada, así que el espacio de trabajo no puede enviar.

Qué hacer: contacta con soporte.

number_daily_cap_reached#

HTTP 429. El número que envía ya ha enviado 1.000 mensajes en las últimas 24 horas (uso justo), o un lote no cabe en lo que queda: requested y room dicen cuántos.

Qué hacer: envía el resto más tarde o desde otro número.

message_rejected#

HTTP 422. El mensaje no se pudo poner en cola; message dice por qué. No se guardó nada.

Qué hacer: corrige lo que describe message y vuelve a enviarlo.

message_not_found#

HTTP 404. No hay ningún mensaje con este id para esta clave: no existe, pertenece a otro espacio de trabajo o se envió desde un número que la clave no puede usar. Una clave de prueba solo ve sus propios mensajes de prueba, y una clave real nunca los ve.

Qué hacer: comprueba el id y que usas el mismo tipo de clave (real o de prueba) que creó el mensaje.

not_cancellable#

HTTP 409. Solo se puede cancelar un mensaje en espera (queued o scheduled), y este ya no lo está. status en el error dice en qué estado está ahora, como sent o cancelled.

Qué hacer: no hay nada que cancelar. Un mensaje que ya se envió no se puede recuperar.

Recordatorios#

invalid_cron#

HTTP 400. schedule.cron no es una expresión cron de 5 partes, o describe un momento que nunca llega (como el 31 de febrero).

Qué hacer: escribe minuto, hora, día del mes, mes y día de la semana, como 0 9 * * 1 para los lunes a las 09:00. Consulta Programación.

invalid_timezone#

HTTP 400. schedule.timezone no es el nombre de una zona horaria IANA.

Qué hacer: usa un nombre como Asia/Kolkata, Europe/London o America/New_York, no una abreviatura como IST ni un desfase como +05:30. Consulta la referencia de zonas horarias.

number_not_connected#

HTTP 422. El from del recordatorio no es un número conectado de este espacio de trabajo.

Qué hacer: conecta primero el número, elige uno conectado u omite from (null) para que lo envíe cualquier número conectado.

reminder_not_found#

HTTP 404. No hay ningún recordatorio con este id: no existe, se eliminó o se envía desde un número que la clave no puede usar.

Qué hacer: comprueba el id con Listar recordatorios.

Medios#

file_too_large#

HTTP 413. El archivo subido pesa más de 64 MB.

Qué hacer: comprímelo o divídelo; si es un vídeo, baja su resolución.

unsupported_file_type#

HTTP 415. El tipo de archivo no se puede enviar por WhatsApp. El tipo se lee de la extensión al final del nombre del archivo.

Qué hacer: comprueba los tipos que puedes subir y deja la extensión en el nombre (price-list.pdf, no price-list).

storage_full#

HTTP 422. El archivo no cabe en el Directorio de medios del espacio de trabajo según su plan. used y limit dicen cuánto se usa y cuánto se permite, en bytes.

Qué hacer: elimina archivos que ya no necesites o pásate a un plan con más almacenamiento.

media_in_use#

HTTP 409. El archivo todavía no se puede eliminar: algo lo va a enviar aún (un mensaje en espera, también de una campaña, un recordatorio activo o un disparador activo de Google Sheets). count dice cuántos.

Qué hacer: cancela o cambia esos primero, o espera a que salgan los mensajes en espera.

upload_failed#

HTTP 502. El archivo no se pudo guardar por nuestra parte.

Qué hacer: vuelve a intentarlo con la misma Idempotency-Key.

Verificación de números#

no_valid_numbers#

HTTP 422. Ninguna de las entradas de numbers es un número de teléfono. skipped dice cuántas entradas había.

Qué hacer: envía números en formato internacional con +, uno por entrada, como +919876543210.

too_many_numbers#

HTTP 422. La verificación tiene más números de los que puede tener una verificación: más de 10.000 entradas en la solicitud, o más números de los que el plan permite por verificación. count y limit dicen cuántos.

Qué hacer: divide la lista en varias verificaciones. Consulta Límites del plan.

number_check_quota_reached#

HTTP 422. La verificación superaría las verificaciones de números del plan para este periodo de facturación. requested, used y limit dicen cuántos.

Qué hacer: verifica menos números, espera al siguiente periodo de facturación o mejora el plan.

number_check_not_found#

HTTP 404. No hay ninguna verificación de números con este id en el espacio de trabajo.

Qué hacer: comprueba el id con Listar verificaciones.

Números#

plan_required#

HTTP 403. El plan del espacio de trabajo no incluye lo que necesita esta solicitud: la API de código QR para conectar un número, los recordatorios para crear, cambiar o reanudar un recordatorio, o la verificación de números para iniciar una verificación de números.

Qué hacer: un Propietario puede mejorar el plan en Precios. Leer lo que ya existe funciona en cualquier plan.

number_limit_reached#

HTTP 403. El plan no tiene sitio para otro número.

Qué hacer: vuelve a conectar un número existente con number_id, quita un número que ya no uses o mejora el plan.

already_connected#

HTTP 409. El número ya está conectado.

Qué hacer: no hay nada que hacer: puedes enviar desde él. Compruébalo con Obtener un número.

connect_in_progress#

HTTP 409. Este número se está conectando en este momento. number_id en el error dice cuál.

Qué hacer: consulta GET /numbers/{id} para ese número en lugar de volver a pedirlo. Tras 10 minutos sin escaneo, puedes volver a pedirlo.

Webhooks#

invalid_webhook_url#

HTTP 422. url no es una dirección pública https://: es http://, está mal formada o apunta a una dirección privada o local.

Qué hacer: usa una dirección https:// en la que tu servidor responda desde internet. Para hacer pruebas en tu ordenador, usa un servicio de túnel que te dé una dirección pública https://.

webhook_limit_reached#

HTTP 403. El espacio de trabajo ya tiene 5 endpoints de webhook.

Qué hacer: quita uno que ya no uses. Un solo endpoint puede recibir todos los tipos de evento.

webhook_not_found#

HTTP 404. No hay ningún endpoint de webhook con este id: no existe o se quitó. Probar o cambiar el secreto de un endpoint detenido también responde esto; al leerlo se muestra active: false.

Qué hacer: comprueba el id con Listar endpoints. Si se detuvo, vuelve a añadirlo.

Modo de prueba#

test_mode_unsupported#

HTTP 403. Una clave de prueba (wbz_test_…) puede enviar, leer y cancelar mensajes de prueba y leer el resto del espacio de trabajo, pero no cambiar nada más: conectar un número, crear, cambiar o eliminar recordatorios, subir o eliminar medios, iniciar una verificación de números o gestionar endpoints de webhook. El filtro status de GET /messages tampoco está disponible para las claves de prueba.

Qué hacer: usa una clave real (wbz_live_…) para estas solicitudes. Consulta Modo de prueba.