Errores de la API

Cada error trae un errorCode estable: úsalo para decidir qué hacer en tu código. El texto de message está pensado para personas y puede cambiar.

{
  "status": 400,
  "error": "Validation Error",
  "errorCode": "VALIDATION_ERROR",
  "message": "Hay un dato que corregir: el destinatario debe ser un teléfono en formato E.164 (ej. +5215555550001).",
  "fieldErrors": [{ "field": "to", "message": "debe ser un teléfono en formato E.164" }],
  "docsUrl": "https://pulsend.e2ecore.com/docs/errors#validation-error",
  "errorId": "fdf24db5-…",
  "path": "/api/v1/messages"
}

Si escribes a soporte, incluye el errorId: con él encontramos tu solicitud.

Índice

Autenticación y permisos

`UNAUTHENTICATED`

HTTP 401

Qué pasó: La solicitud no trae credenciales.
Qué hacer: Envía el encabezado Authorization: Bearer plsm_… con una llave activa. Las llaves se crean en el panel, en Desarrolladores › Llaves de API.

`INVALID_API_KEY`

HTTP 401

Qué pasó: La llave no existe, fue revocada o ya venció.
Qué hacer: Revisa que la copiaste completa (empieza con plsm_, sin espacios ni saltos de línea). Si la revocaste o venció, crea una nueva: la llave completa solo se muestra una vez, al crearla.

`FORBIDDEN_CAPABILITY`

HTTP 403

Qué pasó: La llave es válida, pero no tiene el permiso que pide ese endpoint (por ejemplo, messages:read para consultar un envío).
Qué hacer: Crea una llave con el permiso que falta. Los permisos de una llave no se pueden ampliar después de crearla.

`MODULE_DISABLED`

HTTP 403

Qué pasó: Tu cuenta no tiene activado el módulo que usa ese endpoint (por ejemplo, la agenda de citas).
Qué hacer: Un administrador de la cuenta puede activarlo en Configuración › Módulos. Si tu plan no lo incluye, el panel te dice qué plan lo trae.

Datos de la solicitud

`VALIDATION_ERROR`

HTTP 400

Qué pasó: Falta un campo obligatorio o uno trae un valor inválido. fieldErrors dice cuál y por qué.
Qué hacer: Corrige los campos que indica fieldErrors. Los teléfonos van en formato E.164, con + y código de país: +5215555550001.

`BAD_REQUEST`

HTTP 400

Qué pasó: La solicitud no se puede leer: JSON mal formado, un parámetro con el tipo equivocado o un encabezado obligatorio que falta.
Qué hacer: El message nombra el dato con problema. Valida tu JSON y revisa que los parámetros tengan el tipo que documenta la referencia.

`UNSUPPORTED_MEDIA_TYPE`

HTTP 415

Qué pasó: El cuerpo no llegó como JSON.
Qué hacer: Envía el encabezado Content-Type: application/json y el cuerpo en JSON.

`MESSAGE_VARIABLES_NOT_SUPPORTED`

HTTP 400

Qué pasó: El texto trae variables como {{nombre}}, pero en este envío no hay un contacto del cual tomar sus valores.
Qué hacer: Manda el texto final, con los valores ya sustituidos en tu sistema.

`MEDIA_URL_INVALID`

HTTP 400

Qué pasó: mediaUrl no es una dirección https pública.
Qué hacer: Usa una URL https:// que se pueda abrir sin iniciar sesión.

`MEDIA_NOT_SUPPORTED`

HTTP 422

Qué pasó: Enviaste mediaUrl, pero la ruta de SMS activa no entrega imágenes (MMS). No lo mandamos como texto solo para no cambiar tu mensaje sin avisarte.
Qué hacer: Quita mediaUrl y pon el enlace dentro del texto, o usa un canal que acepte imágenes, como WhatsApp.

`RESOURCE_NOT_FOUND`

HTTP 404

Qué pasó: No hay nada con ese id en tu cuenta. Un id de otra cuenta también responde 404, nunca 403.
Qué hacer: Verifica el id que recibiste al crear el recurso. Los envíos reales (llave de Producción) se siguen por webhooks; GET /api/v1/messages/{id} devuelve solo envíos de prueba.

`IDEMPOTENCY_KEY_REUSED`

HTTP 422

Qué pasó: Ya usaste ese Idempotency-Key con un cuerpo distinto.
Qué hacer: Para reintentar, repite la solicitud original sin cambios: te devolvemos el mismo resultado sin enviar dos veces. Para enviar algo diferente, genera un Idempotency-Key nuevo (un UUID por envío).

`CONFLICT`

HTTP 409

Qué pasó: El recurso ya existe (por ejemplo, un contacto con ese teléfono) o su estado actual no permite la acción.
Qué hacer: Consulta el recurso existente y actualízalo en lugar de crear otro.

`SLOT_TAKEN`

HTTP 409

Qué pasó: Alguien acaba de reservar ese horario.
Qué hacer: Vuelve a pedir la disponibilidad y ofrece otro horario.

Envíos

`LIVE_KEY_REQUIRES_VERIFIED_BUSINESS`

HTTP 422

Qué pasó: Una llave de Producción intentó enviar a un número que no es de prueba, pero tu negocio todavía no está verificado.
Qué hacer: Verifica tu negocio en el panel (Verificar mi negocio). Mientras tanto, integra con una llave de Prueba: los envíos se simulan y no cuestan.

`CONTENT_BLOCKED`

HTTP 422

Qué pasó: El texto coincide con una regla de cumplimiento (por ejemplo, suplantación, préstamos sin licencia o enlaces engañosos) y se detuvo antes de salir.
Qué hacer: Reescribe el mensaje. Si crees que es un error, escríbenos a soporte con el errorId.

`RATE_LIMITED`

HTTP 429

Qué pasó: Hiciste demasiadas solicitudes en poco tiempo.
Qué hacer: Espera los segundos que indica retryAfterSeconds (o el encabezado Retry-After) y reintenta. Reintenta con espera creciente, no en un ciclo inmediato.

Códigos de verificación (Verify)

`VERIFY_INVALID_PHONE`

HTTP 400

Qué pasó: El número no es válido.
Qué hacer: Envíalo en formato internacional E.164, por ejemplo +525512345678.

`VERIFY_COUNTRY_NOT_ALLOWED`

HTTP 422

Qué pasó: No enviamos códigos a números de ese país. El message lista los países habilitados.
Qué hacer: Si necesitas otro país, escríbenos a soporte.

`VERIFY_ACCOUNT_NOT_VERIFIED`

HTTP 422

Qué pasó: Tu cuenta todavía no puede enviar códigos reales.
Qué hacer: Completa la verificación del negocio en el panel. Mientras tanto, prueba con una llave de Prueba.

`VERIFY_RATE_LIMITED`

HTTP 429

Qué pasó: Se pidieron demasiados códigos para el mismo número en poco tiempo. Es una protección contra abuso y contra cobros por SMS falsos.
Qué hacer: Espera retryAfterSeconds antes de pedir otro. En tu interfaz, deshabilita el botón «Reenviar código» durante ese tiempo.

`VERIFY_DAILY_SPEND_CAP_REACHED`

HTTP 429

Qué pasó: La llave llegó a su tope diario de gasto en códigos.
Qué hacer: Se libera a medianoche (UTC). Si tu volumen legítimo es mayor, pide a soporte que lo amplíe.

`VERIFY_INSUFFICIENT_FUNDS`

HTTP 402

Qué pasó: Tu saldo no alcanza para enviar el código.
Qué hacer: Recarga saldo en Facturación › Plan y pagos, o activa la recarga automática para que no vuelva a pasar.

`VERIFY_QUOTA_EXHAUSTED`

HTTP 429

Qué pasó: Usaste todos los envíos que incluye tu plan este mes. El message dice cuándo se renuevan.
Qué hacer: Espera la renovación o mejora tu plan en Facturación › Plan y pagos.

`VERIFY_NOT_FOUND`

HTTP 404

Qué pasó: No hay un código pendiente para ese número o identificador. Puede que se haya reemplazado por uno más nuevo o que ya se haya usado.
Qué hacer: Revisa el dato o solicita un código nuevo con POST /api/v1/verify.

`VERIFY_EXPIRED`

HTTP 410

Qué pasó: El código venció.
Qué hacer: Solicita uno nuevo con POST /api/v1/verify.

`VERIFY_MAX_ATTEMPTS_REACHED`

HTTP 429

Qué pasó: Se agotaron los intentos para este código.
Qué hacer: Solicita un código nuevo con POST /api/v1/verify.

Estados de entrega

Estos no son errores de la solicitud: el envío se aceptó (201 o 202) y el resultado llega en status y errorCode del mensaje, o en tus webhooks.

CHANNEL_OPT_OUT: el destinatario se dio de baja de ese canal. No se envió ni se cobró.
SANDBOX_DELIVERY_FAILED: falla simulada de una llave de Prueba (números terminados en 0002).

Con una llave de Prueba los números que terminan en 0001 (entregado), 0002 (falla), 0003 (entregado y baja), 0004 (leído, WhatsApp) y 0005 (fuera de la ventana de 24 h) simulan cada resultado sin enviar nada real.