Errores y respuestas

La API REST de KintiSoft utiliza códigos de estado HTTP para comunicar el resultado de las solicitudes.

Comprender estos códigos permite identificar problemas de autenticación, errores en los datos enviados, restricciones de acceso y fallos temporales del servicio.

Esta guía explica cómo interpretar las respuestas y gestionar errores de forma segura.

Estructura de una respuesta HTTP

Una respuesta HTTP contiene, entre otros elementos:

• Código de estado: indica el resultado general de la solicitud.
• Encabezados: proporcionan información adicional sobre la respuesta.
• Cuerpo: contiene datos o información del error, cuando corresponde.

Los endpoints de KintiSoft pueden devolver información JSON según la operación solicitada.

Códigos de estado HTTP

Los códigos HTTP se clasifican en diferentes grupos.

Rango	Significado
2xx	La solicitud se procesó correctamente.
3xx	Redirección o tratamiento adicional.
4xx	La solicitud no pudo procesarse por una condición relacionada con el cliente.
5xx	Se produjo un error en el servidor o en el procesamiento del servicio.

Respuestas exitosas

Los códigos 2xx indican que la operación se ha procesado correctamente.

Código	Descripción
200 OK	La solicitud fue procesada correctamente.
201 Created	Se creó un recurso.
202 Accepted	La solicitud fue aceptada para su procesamiento.
204 No Content	La operación finalizó sin devolver contenido.

nota

No todos los endpoints utilizan todos estos códigos. Consulta la API Reference para conocer las respuestas específicas de cada operación.

Respuestas sin contenido

Algunas operaciones HTTP pueden devolver un estado exitoso sin cuerpo de respuesta.

Por ejemplo, una respuesta 204 No Content no debe procesarse como JSON.

Respuestas de error

Cuando una solicitud falla, la API puede devolver un código HTTP de error y un cuerpo con información adicional.

La documentación actual de KintiSoft incluye errores de autenticación con una estructura como la siguiente:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid."
  }
}

Campos del ejemplo documentado

Campo	Descripción
error	Objeto con información del error.
code	Identificador del tipo de error.
message	Descripción del error.

aviso

Este formato está documentado para determinados errores de autenticación. No debe asumirse que todos los endpoints utilizan exactamente la misma estructura sin verificar sus contratos de respuesta.

Errores del cliente

Los códigos 4xx representan situaciones en las que la solicitud no puede completarse bajo las condiciones actuales.

Código	Significado habitual	Acción recomendada
400	Solicitud inválida	Revisar parámetros y cuerpo.
401	Autenticación requerida o inválida	Verificar credenciales.
403	Acceso no permitido	Revisar permisos.
404	Recurso no encontrado	Comprobar la ruta y el identificador.
405	Método no permitido	Revisar el método HTTP admitido.
409	Conflicto con el estado del recurso	Revisar el estado actual.
422	Datos no procesables	Revisar las reglas de validación.
429	Límite de solicitudes alcanzado	Aplicar la política de reintentos correspondiente.

Estos son significados habituales del protocolo HTTP. La disponibilidad de cada código depende del endpoint y de la implementación de KintiSoft.

Errores de autenticación

API Key inválida

Ejemplo documentado:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid."
  }
}

Verifica que:

1. La credencial sea correcta.
2. La API Key continúe activa.
3. Estés utilizando el tenant correspondiente.
4. El encabezado Authorization tenga el formato adecuado.

Encabezado de autorización ausente

{
  "error": {
    "code": "missing_authorization_header",
    "message": "Authorization header is required."
  }
}

Incluye la credencial en el encabezado:

Authorization: Bearer YOUR_API_KEY

Permisos insuficientes

{
  "error": {
    "code": "insufficient_permissions",
    "message": "You do not have permission to access this resource."
  }
}

Verifica los permisos asociados a la API Key y confirma que la operación esté autorizada.

Para más información, consulta Autenticación.

Errores del servidor

Los códigos 5xx indican que el servidor no pudo completar la solicitud.

Código	Significado habitual
500	Error interno del servidor.
502	Respuesta inválida de un servicio intermedio.
503	Servicio temporalmente no disponible.
504	Tiempo de espera agotado en un servicio intermedio.

Estos códigos no significan necesariamente que la solicitud deba repetirse inmediatamente.

Antes de reintentar, considera el tipo de operación y la posibilidad de que haya sido procesada parcialmente.

Manejo de errores en JavaScript

El siguiente ejemplo muestra cómo interpretar códigos HTTP y gestionar posibles respuestas JSON.

async function requestKintiSoft(url, apiKey) {
  const response = await fetch(url, {
    method: "GET",
    headers: {
      Authorization: `Bearer ${apiKey}`,
      Accept: "application/json",
    },
  });

  const contentType =
    response.headers.get("content-type") || "";

  let data = null;

  if (contentType.includes("application/json")) {
    data = await response.json();
  } else {
    data = await response.text();
  }

  if (!response.ok) {
    const error = new Error(
      `Error HTTP ${response.status}`
    );

    error.status = response.status;
    error.details = data;

    throw error;
  }

  return data;
}

Este ejemplo ilustra el manejo general de HTTP. No presupone un formato único de respuesta para todos los endpoints.

Estrategias de manejo de errores

1. Validar antes de enviar

Comprueba los datos obligatorios y sus formatos antes de realizar una solicitud.

Esto reduce errores evitables y solicitudes innecesarias.

2. Diferenciar errores recuperables

No todos los errores deben tratarse de la misma manera.

Tipo de situación	Estrategia
Credenciales incorrectas	Corregir la autenticación.
Permisos insuficientes	Revisar la autorización.
Datos inválidos	Corregir la solicitud.
Recurso inexistente	Revisar identificadores y contexto.
Fallo temporal del servidor	Evaluar un reintento controlado.
Error de red	Verificar conectividad y estado de la operación.

3. Implementar reintentos controlados

Los reintentos pueden ser útiles ante fallos transitorios, pero deben realizarse con precaución.

Considera:

• Utilizar tiempos de espera entre intentos.
• Aplicar backoff exponencial.
• Limitar el número de reintentos.
• Respetar Retry-After cuando esté disponible.
• Evitar repetir operaciones que puedan generar duplicados.

:::warning Idempotencia No reintentes automáticamente operaciones de creación o modificación si desconoces si la solicitud anterior se completó.

Verifica primero las garantías de idempotencia del endpoint. :::

4. Registrar información útil

Para diagnosticar fallos, registra información como:

• Endpoint utilizado.
• Método HTTP.
• Código de respuesta.
• Momento de la solicitud.
• Identificador de correlación, cuando el servicio lo proporcione.
• Código de error documentado, si existe.

Evita registrar API Keys, tokens y datos sensibles.

5. Mostrar mensajes adecuados

Los mensajes técnicos no siempre son apropiados para los usuarios finales.

Tu aplicación puede convertir un error en una explicación comprensible, conservando los detalles técnicos necesarios para diagnóstico.

Buenas prácticas

• Gestiona los códigos HTTP explícitamente.
• No presupongas que todas las respuestas contienen JSON.
• Comprueba el estado antes de procesar los datos.
• Evita exponer información sensible en mensajes de error.
• Implementa reintentos únicamente cuando sea seguro.
• Consulta la referencia del endpoint para verificar códigos y esquemas.
• Diferencia los errores HTTP de las validaciones funcionales del negocio.

Recursos relacionados

• Introducción a la API
• Autenticación
• Inicio rápido