Errores, reintentos y duplicados

Cuando una llamada falla, la respuesta trae un código HTTP y un cuerpo con detail, que dice qué falló en palabras. Un envío de carta que responde un error (4xx) no envió nada.

La forma de un error

{ "codigo": "cuando_falta", "detail": "Esta carta espera que le digan para cuándo: falta «cuando»." }

Campo	Qué es
codigo	Estable. Es contra lo que se programa: un if codigo == "carta_sin_lista". No cambia en la versión.
detail	Qué pasó, en palabras, para leerse en un registro tal cual. Puede mejorar mañana. Con cuerpo_invalido es la lista de campos que no tienen la forma esperada.
cuenta, filas, avisos	Solo en algunos errores de envío: la revisión fila a fila cuando ninguna puede salir, o a quién no se alcanzó.

Léalo así: el código dice qué, el detalle dice por qué esta vez.

Los códigos

Código	HTTP	Qué significa
grant_no_soportado	400	Solo se acepta grant_type=client_credentials.
credencial_invalida	401	El client_id o el secreto no casan, o la credencial no vale.
no_autenticado	401	Falta la credencial, no vale, está revocada o caducó.
sin_permiso	403	La credencial vale, pero no abre esta familia.
no_encontrado	404	No existe en tu cliente. Lo de otro cliente responde igual.
demasiado_grande	413	El archivo pesa más de lo permitido.
archivo_inalcanzable	422	No se pudo traer archivo_url: tiene que ser https y alcanzable desde internet.
archivo_invalido	422	El archivo no se puede leer, o archivo.datos no es base64.
archivo_no_arranca	422	El archivo entero no puede salir: le faltan columnas, pasa un tope o no trae filas.
campo_desconocido	422	El envío trae un campo que no existe; detail dice cuáles acepta.
canal_desconocido	422	El canal de solo_por no existe.
carta_apagada	422	La carta está apagada.
carta_con_audiencia	422	La carta tiene su propia audiencia: no recibe lista.
carta_sin_capacidad	422	La carta no tiene capacidad: se borró la que decía qué contar.
carta_sin_lista	422	La carta espera la lista de quien la envía y no llegó.
cuando_falta	422	La carta espera que le digan para cuándo y no llegó cuando.
cuando_invalido	422	cuando no es una fecha ISO 8601 con su zona horaria.
cuando_no_aceptado	422	La carta decide su propio cuándo: no recibe cuando.
cuando_pasado	422	La fecha de cuando ya pasó.
cuerpo_invalido	422	El cuerpo no tiene la forma esperada: detail lista los campos.
datos_faltan	422	Falta un dato obligatorio del mensaje; detail dice cuál.
datos_invalidos	422	datos tiene que ser un objeto: nombre del dato → valor.
lista_duplicada	422	La lista llegó de más de una forma: para, archivo o archivo_url, solo una.
ninguna_fila_sale	422	Ninguna fila de la lista puede salir; detail trae cada una con su motivo.
no_valido	422	La llamada se entiende pero no se puede hacer así; detail dice por qué.
para_invalido	422	para tiene que ser una lista.
sin_destinatarios	422	No hay a quién escribirle.
demasiados_intentos	429	Demasiados intentos: espera los segundos de Retry-After.
fallo_interno	500	Un fallo de ELYRA. Reintenta más tarde.

Un error HTTP corriente que no tenga código propio sale con el genérico de su estado (no_encontrado para un 404, no_valido para un 422).

Cuándo reintentar

• Sí: no_autenticado con un token (tras pedir otro), demasiados_intentos (tras esperar Retry-After), fallo_interno y los fallos de red o de tiempo de espera. Con una pausa que crece entre intentos (1 s, 2 s, 4 s…).
• No: sin_permiso, no_encontrado, demasiado_grande y todos los 422. Repetir la misma llamada da el mismo error; hay que cambiar algo primero.

Que un reintento no mande dos veces

El caso peligroso es el tiempo de espera agotado: el sistema no sabe si ELYRA recibió el envío, reintenta, y la alerta llega dos veces. Para eso existe id_envio:

• Se manda un identificador propio en cada envío de carta: el número del incidente, el de la factura, uno generado.
• Si ELYRA ya tiene un envío con ese id_envio, no envía de nuevo: responde 200 con {"repetido": true, "envio": {…}}, el envío que ya existe.
• Un envío que se canceló no cuenta: el mismo id_envio puede volver a usarse.

Léalo así: con id_envio, reintentar siempre es seguro.

Lo que no es un error

• Una persona a la que el canal no deja escribir (WhatsApp fuera de su ventana de 24 horas, alguien que pidió no recibir avisos) no hace fallar el envío: esa fila sale en la cuenta como «no salió» o «puede no salir», con su motivo, y las demás siguen.
• Un aviso suelto (POST /avisos) vuelve siempre con su registro y su estado: un rechazo del canal es un estado con motivo, no un error HTTP.

Los topes

Qué	Tope de fábrica
Destinatarios por envío de carta	500
Tamaño de un archivo	2 MB
Destinatarios al día, entre todos los envíos	2.000
Direcciones en un aviso suelto	100

Los tres primeros se cambian en Personas, en los ajustes de los lotes. Pasar un tope responde 422 diciendo cuál, y no se envía nada.

Relacionado: Referencia interactiva, con el error que puede devolver cada llamada.