Manejo de Errores

Cuando una solicitud a la API de integración falla, la respuesta incluye un cuerpo JSON con información sobre el error.

Formato de error

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or revoked API key"
}

Códigos de error

Errores comunes y diagnóstico

401 — Clave no reconocida

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or revoked API key"
}

Causas posibles:

• La clave fue revocada desde el panel de administración
• La clave tiene una fecha de expiración vencida
• Error de formato (espacios, caracteres extra)
• El dueño de la clave está inactivo — en ese caso el message es API key owner is inactive or not found
• La API no pudo validar la clave en ese momento — en ese caso el message es API key validation failed; reintenta la solicitud

Una solicitud que no lleva clave no recibe este 401. La API solo lee x-api-key como clave cuando su valor empieza con rtn_sk_; cualquier otro valor cuenta como si no hubiera clave. Sin clave y sin x-tenant-id, la API responde 400 Bad Request con Missing required header: x-tenant-id; con x-tenant-id pero sin credenciales, responde 401.

Errores de proyecto

En GET /api/integration/activities/tasks y POST /api/integration/activity-results/tasks, x-project-id es opcional: los dos son endpoints project-optional. Cuando se envía el header, la API lo verifica antes que los permisos y el cuerpo. El 400 de un resultado sin activity_id no es parte de esa verificación: llega después de validar el cuerpo, así que un error en el cuerpo se informa primero. Cómo elige su proyecto cada clave se explica en Alcance de la clave.

403 — Permiso insuficiente

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Required permissions: activity:view"
}

Causas posibles:

• La clave no incluye el permiso requerido para el endpoint
• Pide al dueño de la clave que edite sus permisos con PUT /api/api-keys/:id/permissions o desde Configuración → Claves API

400 — Error de validación

La API responde 400 cuando el cuerpo no cumple el formato documentado.

Causas posibles:

• Campos requeridos faltantes: occurred_at y task_result.result siempre; commerce_external_id solo cuando no viene activity_id (ejecuciones independientes)
• Formato de fecha inválido (debe ser ISO 8601)
• activity_id no es un UUID válido
• Campos que no forman parte del cuerpo documentado

422 — Estado no procesable

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "La actividad no está en un estado válido para registrar resultado."
}

Causas posibles:

• La actividad vinculada no está en un estado que admita resultado. READY, DISPATCHED y RETRYING lo admiten; COMPLETED también, y enviar de nuevo actualiza el resultado existente de la actividad; CANCELED y FAILED no — message de arriba
• La fecha de ejecución de la actividad ya cruzó el cierre de fin de día — La actividad corresponde a un día ya cerrado y no admite registrar resultado. A partir de ese corte se ejecuta un cierre automático que puede registrar el resultado (como NOT_EXECUTED). Las ejecuciones independientes (STANDALONE, sin activity_id) están exentas de esta regla y de la anterior
• El código de resultado de task_result.result no existe o no está activo — El tipo de resultado seleccionado no está activo. Consulta Listar Configuraciones para obtener códigos válidos
• El tipo de resultado requiere task_result.future_scheduled_at y no se envió — Este tipo de resultado requiere una fecha comprometida.
• task_result.future_scheduled_at cae en un día anterior a hoy, en la zona horaria del tenant — La fecha programada no puede ser en el pasado.