API para integradores Referencia
API de leads: mensajes y códigos de error
Cada respuesta de error de la API con su código estable, el campo que falla y qué hacer para corregirlo.
En esta página
En resumen
- Un error llega con
statuserror, unmessageen inglés, uncodeestable y, si falla un campo,field. Programa contracode. - Casi todo llega con HTTP 200. Sólo
invalid_json(400) einternal_error(500) cambian el código HTTP. - Llega un solo error, el primero que falla.
- Hasta el duplicado, un rechazo no guarda el lead: corrígelo y reenvíalo. Desde la entrega (
rejected_by_advertiser,advertiser_unreachableycampaign_not_ready) el lead queda guardado: no lo reenvíes.
Para qué sirve
Para saber qué ha pasado con un lead que no se acepta y si tiene sentido volver a mandarlo. Cómo se monta la petición está en API de leads: enviar un lead (referencia).
Cómo es una respuesta de error
{"status":"error","message":"The field \"phone_lead\" is required for this campaign.","code":"missing_field","field":"phone_lead"}codeno cambia con el tiempo; el texto demessagepuede mejorar.fieldlleva el nombre del parámetro, y en una pregunta de la campañacustom_data.y su clave. Los errores que no son de un campo no lo llevan.- Fuera de horario, la respuesta lleva además
opens_at. - Las comillas de los mensajes llegan escapadas (
\"): léelos con un decodificador JSON.
Las comprobaciones, en orden
El lead se comprueba en este orden y recibes el primer fallo: correo, que venga el token, fecha de nacimiento, género, país, IP, fuente, lista negra, que el token sea de un afiliado, elección de campaña (horario, requisitos y tope diario), duplicado y, por último, la entrega al comprador.
Por eso un token inventado con un correo mal escrito recibe el error del correo: para saber si el token es bueno, todo lo anterior tiene que estar bien.
Todos los códigos
code | HTTP | message | Cuándo | Qué hacer |
|---|---|---|---|---|
invalid_json | 400 | Invalid JSON Payload | El cuerpo no es un objeto JSON con algún dato dentro. | Corrige el JSON y reenvía. |
missing_field · invalid_field (email_lead) | 200 | The provided email does not meet quality standards. | Falta el correo o no es válido. | Corrige y reenvía. |
unknown_affiliate | 200 | The affiliate does not exist. | Falta token_affiliate o no es de ningún afiliado. | Copia el token de tu guía. |
invalid_field (birthdate_lead) | 200 | The birth date format is incorrect. | No es AAAA-MM-DD. | Corrígelo u omite el campo. |
invalid_field (gender_lead) | 200 | Gender must be M or F. | Otro valor que M o F. | Corrígelo u omite el campo. |
missing_field · invalid_field (country_lead) | 200 | The country format is incorrect. | Falta el país o no tiene dos caracteres. | Manda el código de dos letras. |
missing_field · invalid_field (ip_lead) | 200 | Geolocation failure for this lead. | Falta la IP o no es una IP. | Manda la IP del usuario. |
missing_field · invalid_field (id_source) | 200 | The provided id_source is invalid. | Falta la fuente o no existe. | Manda la fuente que te indique tu red. |
blacklisted | 200 | Lead rejected due to blacklist. | El correo o su dominio están en la lista negra. | Ese contacto no entra. |
missing_field · invalid_field (los de la campaña) | 200 | The field "<campo>" is required for this campaign. o The field "<campo>" is not valid for this campaign: <motivo>. | La campaña exige ese dato o un formato. | Corrige y reenvía. |
outside_schedule | 200 | The campaign is not accepting leads right now (outside its receiving hours). | La campaña está fuera de su horario. | Reenvía a partir de opens_at. |
no_campaign_available | 200 | No active campaigns available within the daily limit for this affiliate and country. | Ninguna campaña tuya acepta el lead. | Ver más abajo. |
duplicate | 200 | Duplicate lead: This email or phone number is already registered for this campaign. | Esa campaña ya tiene un lead con ese correo o ese teléfono. | No lo reenvíes a esa campaña. |
rejected_by_advertiser | 200 | Lead rejected by the advertiser. o Lead rejected by the advertiser: <motivo> | El comprador lo recibió y no lo aceptó. | No lo reenvíes a esa campaña. |
advertiser_unreachable | 200 | The advertiser could not be reached. The lead has not been delivered. | El comprador no respondió o el correo no pudo salir. En algunas campañas, un comprador que no responde da campaign_not_ready. | No lo reenvíes: habla con tu red. |
campaign_not_ready | 200 | This campaign is not ready to receive leads yet. Please contact your account manager. | La campaña no puede entregar por algo de la red: le falta configuración, fallan sus credenciales con el comprador o, en algunas campañas, el comprador no respondió. | No lo reenvíes: habla con tu red. |
internal_error | 500 | Internal Server Error | Un fallo inesperado. | Revisa tamaños y tipos de los campos; si sigue, habla con tu red. |
Un lead aceptado no lleva code: {"status":"success","message":"Lead successfully registered."}.
Qué rechazos dejan el lead guardado
| No se guarda (puedes corregir y reenviar) | Queda guardado (no lo reenvíes) |
|---|---|
invalid_json, missing_field, invalid_field, unknown_affiliate, blacklisted, no_campaign_available, outside_schedule y duplicate | rejected_by_advertiser, advertiser_unreachable y campaign_not_ready |
Un lead que no se guarda no gasta plaza ni tope. El que queda guardado sí cuenta para los duplicados: reenviarlo a la misma campaña suele dar duplicate, también tras un campaign_not_ready cuando la red ya ha arreglado la campaña. internal_error puede pasar antes o después de guardarse.
Los requisitos de la campaña
Tras los dos puntos de invalid_field va lo esperado, en inglés. Por ejemplo:
{"status":"error","message":"The field \"custom_data.tipo_vivienda\" is not valid for this campaign: it must be one of: Piso, Casa.","code":"invalid_field","field":"custom_data.tipo_vivienda"}Otros motivos: it must be letters only (spaces, hyphens, apostrophes and dots are allowed), it must be a Spanish mobile or landline number, it must be a Spanish postal code (5 digits, e.g. 28001), it must have between N and M characters, the lead must be at least N years old o it must be a single value, not a list or an object. Qué pide cada campaña y cada formato: API de leads: requisitos, duplicados y horario de cada campaña.
Fuera de horario: cuándo reenviar
{"status":"error","message":"The campaign is not accepting leads right now (outside its receiving hours).","code":"outside_schedule","opens_at":"2026-10-27T09:00:00+01:00"}opens_at es la próxima apertura, en formato ISO 8601 con el desfase de la zona horaria de la campaña. El lead no se ha guardado: reenvíalo a partir de esa hora y no contará como duplicado. Si la campaña no vuelve a abrir en los próximos 400 días, opens_at no viene.
Sólo recibes outside_schedule si todas las campañas que podían recibir el lead estaban cerradas. Si otra estaba abierta y lo aceptó, el lead va a ésa.
no_campaign_available
El mensaje habla del límite diario, pero sale por cualquiera de estas causas:
- no tienes una asignación activa a esa campaña, o a ninguna de ese país si no mandas
id_campaign; - la fuente (
id_source) no es la de tu asignación; - la campaña está pausada;
- el tope total o el diario de la asignación están llenos.
Revisa id_campaign e id_source y, si son correctos, consulta con tu red.
rejected_by_advertiser
El motivo tras los dos puntos sólo sale cuando el comprador lo da en un campo que la plataforma sabe leer. Llega limpio: sin HTML, sin direcciones web ni correos, sin números largos y con 200 caracteres como mucho. Lo que el comprador recibió y su respuesta completa no te llegan.
Lo que conviene saber
- Corregir un error puede destapar el siguiente: sólo llega uno por respuesta.
- El mismo envío puede cambiar de código según la hora (horario) y, sin
id_campaign, según la campaña que se pruebe primero, que se elige al azar. - Los rechazos que no guardan el lead sólo los recibes tú: la red no los ve en ninguna pantalla. Si le preguntas por uno, dale el
codey elfield. - Una entrega fallida no se repite sola.