Gestionar errores

Todo lo que falla en el SDK llega como un UtiliaSDKError: una respuesta de error de la API, un fallo de red o un dato que el propio SDK rechaza antes de enviarlo. Así puedes tratar todos los casos con un único bloque de captura y decidir qué hacer mirando un código, no el texto del mensaje.

Qué trae el error

readErrorGuidance (read_error_guidance) saca esos tres primeros datos de cualquier cuerpo de error, también si llamas a la API por tu cuenta. Qué significa cada errorCode y qué hacer con él está en Errores, identificador de petición y reintentos.

Códigos y respuestas HTTP

Comprobaciones rápidas

El error trae comprobaciones ya hechas. En JavaScript son métodos (con paréntesis); en Python, propiedades (sin paréntesis).

Desde la 4.6.0, la función isInsufficientScopeError(error) (is_insufficient_scope_error(error)) dice si falta un permiso de la API, y error.requiredScopes (error.required_scopes), cuál.

Para registrar el error en tus trazas, toJSON() (to_dict() en Python) lo convierte en un objeto plano con el código, el mensaje, la fecha, el estado HTTP, el identificador de petición y el contexto de plan.

Capturar y reaccionar

Mira primero si es un bloqueo de plan y después el code, nunca el texto del mensaje. Cuando el error te llega, el SDK ya ha reintentado lo que tenía sentido reintentar.

El mismo criterio, en código:

import { ErrorCode, UtiliaSDKError } from '@utilia-os/sdk-js';
 
try {
  await sdk.tickets.create({
    user: { externalId: 'usr_123' },
    title: 'Error en el formulario de pago',
    description: 'Al enviar el formulario aparece un error 500 en la consola.',
  });
} catch (error) {
  if (!(error instanceof UtiliaSDKError)) throw error;
 
  if (error.isPlanError()) {
    // No se arregla reintentando ni dando permisos: hay que contratar.
    return;
  }
 
  switch (error.code) {
    case ErrorCode.VALIDATION_ERROR:
      console.error('Datos no válidos:', error.message);
      break;
    case ErrorCode.UNAUTHORIZED:
      console.error('Revisa la clave o la sesión OAuth.');
      break;
    case ErrorCode.FORBIDDEN:
      // Desde la 4.6.0, requiredScopes dice qué permiso de la API falta.
      console.error('Falta un permiso:', error.requiredScopes ?? error.errorCode, error.docsUrl);
      break;
    case ErrorCode.NOT_FOUND:
      console.error('No existe:', error.errorCode);
      break;
    case ErrorCode.CONFLICT:
      console.error('Choca con el estado del recurso:', error.errorCode);
      break;
    default:
      console.error(`[${error.code}] ${error.message} (petición ${error.requestId})`);
  }
}

Errores de las credenciales

Desde la 4.2.0, los dos SDK conocen y tipan los códigos de negocio de las credenciales. En JavaScript, CREDENTIAL_ERROR_CODES los reúne, isCredentialErrorCode(error.errorCode) dice si un código es de esa familia y el tipo KnownErrorCode tipa error.errorCode. En Python, CredentialErrorCode (comparable con error.error_code) e is_credential_error_code. Los que más vas a ver:

Confirmar una operación en el móvil

Algunas operaciones MCP, como renovar la clave de una aplicación externa o su clave de firma, piden a la persona que las confirme en el móvil si tiene la verificación en dos pasos. La primera llamada falla con APPROVAL_REQUIRED, y getApprovalChallenge(error) (get_approval_challenge en Python) devuelve approvalId, el número (number) que la persona tiene que elegir y expiresAt. Cuando lo aprueba, repite exactamente la misma llamada con twoFactorApprovalId (two_factor_approval_id). isApprovalRequired(error) (is_approval_required) responde si el error es de este tipo. El SDK nunca acepta códigos de verificación por esta vía.

import { getApprovalChallenge } from '@utilia-os/sdk-js';
 
try {
  await sdk.mcp.integrations.appsRegenerateApiKey(appId, { graceDays: 7 });
} catch (error) {
  const reto = getApprovalChallenge(error);
  if (!reto) throw error;
  console.log(`Elige el número ${reto.number} en el móvil.`);
  // Cuando la persona lo apruebe:
  await sdk.mcp.integrations.appsRegenerateApiKey(appId, {
    graceDays: 7,
    twoFactorApprovalId: reto.approvalId,
  });
}

Si la persona no puede aprobarla en su móvil, renueva la clave desde la ficha de la aplicación, con su código de verificación.

Reintentos

El SDK ya reintenta por su cuenta los errores de red, los 429 y los 5xx, hasta el número total de intentos de retryAttempts (retry_attempts), que por defecto es 3. Desde la 4.6.0:

• Espera lo que pide el servidor. Con Retry-After espera ese tiempo. X-Utilia-Quota-Reset solo cuenta en el 429 del cupo por hora agotado que no trae Retry-After; un 5xx u otro 429 sin Retry-After se repite con la espera creciente de siempre: 0,5 s, 1 s, 2 s… Si el servidor pide más de maxRetryAfterMs (max_retry_after, un minuto por defecto), como cuando se agota el cupo por hora, no reintenta: el error llega enseguida con retryAfterMs (retry_after).
• No repite lo que podría duplicar. Un POST sin clave de idempotencia (una alta de ticket, mensaje, cliente, lead, archivo o IA) se intenta una sola vez, y las escrituras que mueven dinero, como invoices.create e invoices.cancel, también. Si repites una a mano, conserva la clave de idempotencia y los datos originales.

Los detalles están en Configurar el cliente.

El envío de errores va aparte: errors.reportBatch y ai.reportError (report_batch, report_error) hacen un solo intento, y la cola de errors.install y capture tiene sus propios reintentos, que nunca repiten antes de lo que pide Retry-After (Capturar los errores de tu aplicación).

Si prefieres controlar tú los reintentos, pon retryAttempts: 1 (o retry_attempts=1), usa la comprobación isRetryable y, cuando el servidor diga cuánto esperar, respeta retryAfterMs (retry_after, en segundos):

import { UtiliaSDKError } from '@utilia-os/sdk-js';
 
async function withRetry<T>(fn: () => Promise<T>, maxAttempts = 3): Promise<T> {
  for (let attempt = 1; ; attempt++) {
    try {
      return await fn();
    } catch (error) {
      const retryable = error instanceof UtiliaSDKError && error.isRetryable();
      if (!retryable || attempt === maxAttempts) throw error;
      const waitMs = error.retryAfterMs ?? 1000 * 2 ** (attempt - 1);
      await new Promise((resolve) => setTimeout(resolve, waitMs));
    }
  }
}
 
const ticket = await withRetry(() => sdk.tickets.get('ticket-uuid', 'usr_456'));

Errores antes de enviar la petición

El SDK comprueba algunos datos antes de llamar a la API. Cuando falla una de esas comprobaciones, el error no tiene código HTTP ni identificador de petición, porque la petición no llegó a salir.

La lista completa de comprobaciones y sus límites está en Límites y validaciones.

Siguiente paso

• Errores de planDistingue un aplicativo o una capacidad sin contratar de un permiso que falta.
• Errores, identificador de petición y reintentosEl mismo tema visto desde la API REST, con los códigos de negocio más habituales.