Errores

Cada error, en toda la API, usa un único envoltorio, para que puedas gestionar los fallos con una sola ruta de código.

Forma del error

sobre de error

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The request was invalid.",
    "details": [
      { "path": "declaredNumber", "message": "must be E.164" }
    ]
  }
}

El estado HTTP coincide con el code. details solo está presente en los errores de validación.

Códigos de error

Código	HTTP	Cuándo
UNAUTHORIZED	401	Clave ausente o inválida.
FORBIDDEN	403	La clave carece del ámbito requerido.
NOT_FOUND	404	No existe tal recurso en tu cuenta.
VALIDATION_FAILED	400	El cuerpo o la consulta de la solicitud eran inválidos.
CONFLICT	409	La acción entra en conflicto con el estado actual (p. ej. enviar desde un número que no está conectado).
RATE_LIMITED	429	Demasiadas solicitudes. Reduce el ritmo y reintenta.
OUTBOUND_LIMIT	429	El tope de contacto en frío: este número inició demasiadas conversaciones NUEVAS esta hora. Las respuestas nunca se cuentan. Espera lo que indique Retry-After y mantén moderado el volumen de primeros contactos.
SLOT_REQUIRED	402	Conectar un número requiere un slot libre.
ACCOUNT_SUSPENDED	402	Toda la cuenta está en espera. Todas las rutas responden esto salvo el inicio de sesión y la facturación. La clave es válida y reintentar no ayuda: contacta con nosotros para restablecer el acceso.
TRANSPORT_UNAVAILABLE	503	El servicio de conexión no está disponible brevemente. Reintenta en breve.
TRANSPORT_BUSY	503	El servicio de mensajería está ocupado. Espera lo que indique la cabecera Retry-After y vuelve a intentarlo; todo lo ya emitido sigue siendo válido.
BILLING_UNAVAILABLE	503	Este despliegue no tiene configurado ningún procesador de pagos.
INTERNAL	500	Un error inesperado de nuestro lado.

Esperar y reintentar

Tres códigos te piden esperar, y significan cosas distintas. RATE_LIMITED significa baja el ritmo. OUTBOUND_LIMIT significa deja de escribir a personas nuevas durante un rato: las respuestas siguen saliendo, y el presupuesto pertenece al número, no a tu clave. TRANSPORT_BUSY significa que el servicio de mensajería nos está limitando: es carga, nunca un defecto de tu solicitud, y todo lo ya emitido sigue siendo válido. Los tres llevan Retry-After en segundos cuando se conoce la espera; espera al menos ese tiempo.

429 Too Many Requests

{
  "error": {
    "code": "OUTBOUND_LIMIT",
    "message": "This number has started too many new conversations in the last hour."
  }
}

Errores de validación

Para un error VALIDATION_FAILED, details lista cada campo infractor por path para que puedas mostrar el problema junto al campo correcto.

gestión de errores

const res = await fetch("https://api.sendveo.com/v1/numbers", options)
if (!res.ok) {
  const { error } = await res.json()
  if (error.code === "VALIDATION_FAILED") {
    for (const d of error.details ?? []) showFieldError(d.path, d.message)
  } else {
    showBanner(error.message)
  }
}