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

Códigos de error

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
`409`	Conflict	La actividad ya tiene un resultado registrado	Usa `hard_override: true` en el cuerpo de la solicitud si necesitas sobreescribir el resultado existente

Errores comunes y diagnóstico

401 — Clave no reconocida

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

Causas posibles:

El header x-api-key no está presente en la solicitud
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)

403 — Permiso insuficiente

{
  "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

400 — Error de validación

{
  "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, status, 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)

409 — Resultado duplicado

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Activity already has a result"
}

La actividad ya tiene un resultado registrado. Si necesitas sobreescribir el resultado existente, envía la solicitud nuevamente con "hard_override": true en el cuerpo.

Recomendaciones

Registra los errores: Almacena el cuerpo de la respuesta de error para diagnóstico posterior
Implementa reintentos para errores 5xx (errores del servidor) con backoff exponencial
No reintentes errores 4xx sin corregir la solicitud — estos indican un problema en los datos enviados
Valida antes de enviar: Consulta los tipos de resultado disponibles antes de enviar resultados para evitar errores 400