Manejo de Errores

Formato de errores, códigos de estado y soluciones para la API de integración.

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": "API key missing or invalid"
}

Campo	Tipo	Descripción
`statusCode`	number	Código de estado HTTP
`error`	string	Nombre del error
`message`	string	Descripción detallada del problema

Status	Código	Descripción	Solución
`401`	Unauthorized	Clave de API faltante o inválida	Verifica que el header `x-api-key` esté presente y que la clave no haya sido revocada
`403`	Forbidden	La clave no tiene el permiso requerido	Confirma que la clave tiene los permisos necesarios: `VIEW_ACTIVITIES` para consultar, `SUBMIT_ACTIVITY_RESULT` para enviar resultados
`400`	Bad Request	Error de validación en el cuerpo de la solicitud	Revisa que el cuerpo cumpla con el formato documentado. Verifica tipos de datos, campos requeridos, y códigos de resultado válidos
`404`	Not Found	Recurso no encontrado	Confirma que el `activity_id`, `commerce_external_id` u otro identificador exista en el tenant
`422`	Unprocessable Entity	La solicitud es válida pero el estado de la actividad no permite la operación	Verifica que la actividad esté en estado accionable (`READY` o `DISPATCHED`) y que su fecha de ejecución no haya cruzado el cierre de fin de día

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key missing or invalid"
}

Causas posibles:

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Causas posibles:

La clave no incluye el permiso requerido para el endpoint
Contacta al administrador del tenant para verificar los permisos asignados a la clave

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "task_result.result must be a valid result type code"
}

Causas posibles:

Campos requeridos faltantes (commerce_external_id, occurred_at, task_result.result)
Código de resultado inválido — consulta Listar Configuraciones para obtener códigos válidos
future_scheduled_at faltante cuando el tipo de resultado lo requiere
Formato de fecha inválido (debe ser ISO 8601)

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "La actividad no está en un estado accionable."
}

Causas posibles:

La actividad vinculada no está en un estado accionable (READY o DISPATCHED)
La fecha de ejecución de la actividad ya cruzó el cierre de fin de día — a partir de ese corte, se ejecuta un cierre automático puede registrar el resultado (como NOT_EXECUTED). Las ejecuciones independientes (STANDALONE, sin activity_id) están exentas de esta regla