Saltar a contenido

Errores y troubleshooting

Esta sección describe el shape de los errores, el catálogo de códigos y una tabla de síntomas comunes con su solución.

Shape de un error

Cuando una request falla, la respuesta tiene esta forma sanitizada:

{
  "success": false,
  "error": "<mensaje genérico>",
  "error_id": "1f2e3d4c-0000-0000-0000-abcdef123456",
  "request_id": "9a8b7c6d-0000-0000-0000-112233445566"
}
  • error — un mensaje genérico, apto para mostrar o loguear. No expone detalles internos.
  • error_id — identificador único de este error puntual.
  • request_id — identificador único de la request que lo originó.

Guarda error_id y request_id. Cuando pidas soporte, incluye ambos: permiten correlacionar tu request exacta con nuestros registros y resolver mucho más rápido. Ver reglas de escalación.

Catálogo de códigos

Código Significado Causa típica Cómo resolver
400 Bad Request CSV inválido o mal formado, parámetro faltante o con formato incorrecto. Revisa el CSV (columnas requeridas por tipo, teléfonos en E.164) y el cuerpo del request. Descarga la plantilla con GET /api/csv-template?type=<tipo>.
401 No autenticado Falta el header X-API-Key (o Authorization), o la credencial es inválida/expirada. Verifica que envías X-API-Key: nrn_live_... y que la key sea válida. Para JWT, revisa que el token no haya expirado.
403 Sin permisos Scope read intentando un POST/PATCH/DELETE, o un agent_id no asignado a tu organización. Usa una key con scope full para operaciones de escritura. Confirma el agent_id con GET /api/agents.
404 No encontrado El recurso no existe (campaña, llamada o campaña programada inexistente). Revisa el campaign_id / call_id. Lista lo existente con GET /api/campaigns o GET /api/campaign/scheduled.
409 Conflicto Ya hay una campaña corriendo (límite de campañas activas). Espera a que la campaña activa termine, o detenla/páusala (POST /api/campaign/stop / pause) antes de iniciar otra.
422 Feature no habilitada La funcionalidad solicitada no está habilitada para tu organización. Contacta a tu equipo de Neuron para habilitar la funcionalidad.
429 Demasiadas requests Superaste el límite de uso del endpoint. Respeta el header Retry-After de la respuesta y reintenta después de ese tiempo. Ver Límites de uso.

El cuerpo de error siempre sigue el shape de arriba (success: false + error + error_id + request_id).

Tabla de troubleshooting (síntomas comunes)

Síntoma Causa probable Qué hacer
Todas las requests devuelven 401 Key inválida, mal copiada, o falta el header. Confirma el header X-API-Key y que la key esté activa. Prueba con GET /api/agents.
Un POST/DELETE devuelve 403 pero los GET funcionan Tu key tiene scope read e intentas una escritura. Pide una key con scope full para operaciones de campaña.
Iniciar campaña devuelve 403 con la key correcta El agent_id no está asignado a tu organización. Lista tus agents con GET /api/agents y usa un agent_id de esa lista.
Iniciar campaña devuelve 409 Ya hay una campaña corriendo (máximo 1 activa). Consulta GET /api/campaign/status; detén o espera la campaña activa antes de iniciar otra.
start devuelve 400 CSV mal formado, columnas faltantes, o teléfonos fuera de E.164. Valida contra la plantilla (GET /api/csv-template?type=<tipo>). Verifica que to_number esté en E.164 y que estén las columnas requeridas.
Recibes 429 Superaste el rate limit del endpoint. Lee Retry-After, espera ese tiempo y aplica backoff exponencial. Ver Límites de uso.
GET /api/agents devuelve agents: [] Tu organización aún no tiene agents asignados. Contacta a tu equipo de Neuron para que asignen agents.
Los resultados no aparecen "al instante" Las llamadas y su análisis se procesan de forma asíncrona. Consulta por polling: repite GET /api/analytics/calls con paginación por cursor hasta ver los resultados. No hay push por webhooks (en desarrollo).

Cómo pedir soporte

Cuando un error te bloquee y la solución no esté en esta doc, contacta a tu canal de soporte e incluye siempre:

  1. El código HTTP recibido.
  2. El error_id y el request_id del cuerpo de la respuesta.
  3. El endpoint y el método que llamaste.
  4. Un resumen de lo que esperabas vs. lo que pasó.

Con esos datos el equipo puede ubicar tu request exacta en los registros. Qué temas resuelve el canal automáticamente y qué requiere un humano está en reglas de escalación.