Saltar al contenido principal
La API REST está en acceso anticipado y se habilita por cuenta a pedido. Las claves de API no se emiten todavía desde el panel. Para solicitar acceso, contactar al ejecutivo de cuenta.
La API de DeltaLead usa códigos de estado HTTP estándar para señalar el resultado de cada solicitud. Cuando una solicitud falla, la respuesta incluye un cuerpo JSON con dos campos garantizados: status, siempre con el valor "error", y detail, un identificador estable en snake_case. La lógica de manejo de errores debe ramificar según ese identificador y nunca según texto libre.

​
Formato de la respuesta de error

Todas las respuestas de error siguen esta forma:
​
string
Siempre "error" en una respuesta fallida. Permite distinguir un error de una respuesta exitosa sin mirar el código de estado HTTP.
​
string
Identificador estable del error, en snake_case y legible por máquina. Este es el campo a usar en la lógica de manejo de errores.
El cuerpo no replica el código de estado HTTP: ese dato ya viaja en la respuesta y duplicarlo solo abre la puerta a que las dos fuentes se contradigan.

​
Códigos de estado HTTP

Crear un lead cuyos datos de contacto ya existen no produce un conflicto. Los datos se resuelven sobre el lead existente —es la misma semántica de merge que aplica el Custom Webhook— y la respuesta devuelve ese lead en lugar de crear un duplicado.

​
Errores de validación (422)

Cuando falla la validación del cuerpo de la solicitud, la API devuelve una respuesta 422 con un arreglo errors al mismo nivel que detail, que indica con precisión qué campos son inválidos. Recorrer errors permite mostrar mensajes por campo a los usuarios o en los logs.
​
array
Presente solo en respuestas 422. Cada elemento contiene una clave field (la ruta dentro del cuerpo de la solicitud que falló) y una clave detail con el identificador de la regla de validación incumplida.
Causas habituales de un 422:
  • Números de teléfono que no están en formato E.164 (por ejemplo, +5491122334455 es válido; 011 2233-4455 no)
  • Campos obligatorios ausentes en el cuerpo de la solicitud, como un contact sin email ni phone
  • Valores de enumeración fuera del conjunto permitido (por ejemplo, un valor de status no reconocido)
  • Cadenas de fecha y hora que no siguen el formato ISO 8601

​
Límite de tasa (429)

El límite es de 5 solicitudes por segundo sostenidas por clave de API, con una ráfaga de hasta 10. Al superarlo, la API devuelve 429 Too Many Requests con una cabecera Retry-After que indica cuántos segundos esperar antes de reintentar. Es la única cabecera de recuperación que emite la API.
Conviene implementar backoff exponencial en todas las solicitudes que se reintentan: esperar los segundos indicados en Retry-After en el primer reintento y luego duplicar el tiempo de espera en cada intento posterior (con un tope máximo, por ejemplo 60 segundos), hasta que la solicitud tenga éxito o se agote el presupuesto de reintentos.

​
Errores de servidor (500)

Un 500 Internal Server Error indica una falla transitoria en la infraestructura de DeltaLead. Corresponde reintentar la solicitud con backoff exponencial: la gran mayoría de los errores transitorios se resuelve en pocos segundos. Si un 500 persiste durante más de unos minutos, se puede consultar la página de estado de DeltaLead o contactar a soporte.
Conviene registrar siempre el cuerpo completo de la respuesta de error, no solo el código de estado HTTP. El campo detail es legible por máquina y estable entre versiones de la API, lo que lo hace apto para reglas de alerta y remediación automática. Por ejemplo, se puede detectar lead_not_found y omitir el registro, o capturar validation_error y mostrar el arreglo errors directamente en el panel de un operador.