Códigos de error

La API de integradores usa códigos HTTP estándar. Los errores de validación devuelven JSON con detalle por campo.

Resumen

Código	Significado	Acción recomendada
`202`	Aceptado	Mensaje encolado; consulta estado en el panel.
`400`	Solicitud inválida	Revisa el cuerpo JSON y las cabeceras.
`401`	No autenticado	Verifica `Authorization: Api-Key …`.
`403`	Prohibido	Revisa `X-Organization-ID` y permisos del proyecto.
`404`	No encontrado	Plantilla o recurso inexistente en el tenant.
`422`	Entidad no procesable	Datos válidos en formato pero rechazados por reglas.
`429`	Límite de tasa excedido	Espera y reintenta con backoff exponencial.
`5xx`	Error del servidor	Reintenta; contacta soporte si persiste.

Causas habituales:

{
	"detail": "Las credenciales de autenticación no se proveyeron."
}

La API key es válida pero no puede operar en la organización indicada, o el plan no permite más envíos.

El slug de template no existe en el proyecto asociado a la API key.

Ejemplo cuando la plantilla no existe o el canal no es válido:

{
	"template": ["Plantilla no encontrada o inactiva."],
	"to": ["Este campo es obligatorio."]
}

Campos frecuentes en POST /api/v1/send/:

Campo	Regla
`template`	Slug de plantilla activa en el proyecto.
`to`	Correo destino válido.
`channel`	Actualmente `email`.
`data`	Objeto JSON con variables de la plantilla.

El envío público está limitado por API key (por defecto 120 solicitudes/minuto, configurable con NOTIFY_PUBLIC_SEND_RATE).

{
	"detail": "Solicitud fue limitada. Expected available in 42 seconds."
}

Incluye cabeceras Retry-After cuando aplica. Diseña reintentos idempotentes con Idempotency-Key.

{
	"message_id": 1042,
	"status": "queued",
	"celery_task_id": "a1b2c3d4-...",
	"idempotent_replay": false
}

Si un 5xx persiste, anota message_id, hora UTC y el Idempotency-Key usado al contactar soporte.