Cómo gestionar errores de API: de 401, 422 a la autorrecuperación limitada

Tras un fallo de petición, lo primero que necesita responder el cliente no es cuántos intentos quedan, sino si la operación se ejecutó y qué cambios tienen sentido. La falta de claves, un nombre de plataforma erróneo, parámetros no compatibles y cortes a mitad de respuesta pueden acabar en el mismo bloque catch; si se reintenta de forma unificada, una entrada corregida se transformará en un fallo repetido o podría crear tareas ya existentes de manera duplicada.

Este artículo usa la interfaz REST de EveryInfra como ejemplo para mostrar la jerarquía de errores, la comprobación de directorios y la autorrecuperación limitada. El decisor de ejemplo solo devuelve la siguiente recomendación, sin enviar peticiones, cambiar credenciales ni ampliar automáticamente el rango de datos. El código fuente actual, los sondeos públicos gratuitos y las muestras de negocio históricas se usan por separado, sin deducir todos los comportamientos de fallo autenticado a partir de una única respuesta 400.

Conserva este intento antes de analizar el error

Genera un identificador de operación comercial antes de la llamada para asociar varios intentos bajo la misma intención de negocio. Guarda por separado la hora de inicio y fin, la versión de la petición, la capacidad de destino, el estado HTTP y el ID de petición de servicio disponible de cada intento. El identificador de negocio no es una clave de idempotencia del servidor; si el servicio no declara compatibilidad, no se debe asumir que se desduplicará al reenviarlo con dicho identificador.

El cuerpo de la respuesta también puede ser HTML, texto, contenido vacío o JSON no analizable. Comprueba primero el Content-Type y el estado antes de intentar analizar el error; si el análisis falla, conserva un resumen de diagnóstico mínimo y no escribas el contenido completo de la página de errores directamente en las indicaciones del usuario ni lo entregues al agente como instrucción. Los registros no guardan por defecto claves, URL completas firmadas, cuerpos originales ni otra información personal innecesaria.

El contenedor de errores público actual de EveryInfra incluye error.code, error.message y error.request_id. Organiza el procesamiento según el código y el estado HTTP; el mensaje está pensado para lectura humana. No dependas de que el mensaje en inglés permanezca invariable ni uses la primera URL de una cadena para navegar automáticamente portando credenciales.

Puedes consultar la lista blanca de diagnóstico de OWASP Logging Cheat Sheet para asociar eventos mediante identificadores interactivos y excluir tokens, valores de sesión e información confidencial. La información de depuración debe bastar para localizar este intento sin convertirse en otra credencial o copia de datos de cliente susceptible de uso indebido.

401 y 403: procesamiento independiente para autenticación y permisos

El código HTTP 401 indica que faltan credenciales de autenticación válidas; 403 indica que el servidor rechaza la ejecución. El estado del protocolo aporta un significado general, pero la causa específica depende del código de error del producto. EveryInfra En la implementación actual, la falta de claves, las claves inválidas o caducadas se consideran problemas de autenticación; las restricciones en la línea de productos, las capacidades detalladas y la IP de origen corresponden a problemas de permisos.

Comprueba primero si la petición se envió al servicio correcto, si el encabezado Authorization se configuró según los requisitos de dicho servicio y si el proceso en ejecución lee el entorno esperado. Puedes revisar la existencia de variables y los identificadores de configuración sin imprimir valores secretos. Haber iniciado sesión en la consola del navegador tampoco demuestra que el proceso del servidor haya obtenido la clave de API correcta.

Ante fallos de autenticación consecutivos, suspende la tarea afectada y avisa al responsable; no recorras otras claves, cambies de cuenta ni desactives las restricciones de permisos para recuperar la ejecución. La actualización automática solo aplica a procesos de renovación autorizados explícitamente y compatibles con el producto; ninguna clave de API de larga duración debe tratarse como un token renovable de forma autónoma.

Error en el nombre de capacidad: lee primero los candidatos y contrasta el objetivo

Un error público que no requiere clave se puede observar de este modo. Aquí se introduce deliberadamente un identificador antiguo de google_maps para leer únicamente el directorio sin recopilar reseñas de ubicaciones:

curl --silent --show-error --include --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=google_maps'

El resultado de 2026-09-04 a las 46 (hora de Pekín) es HTTP 400, con error.code como unknown_capability, y la sugerencia contiene google_maps_reviews junto a otro candidato similar. Una capacidad desconocida no debe etiquetarse de forma general como 404, ni se debe cambiar automáticamente la tarea original solo porque el candidato aparezca en primer lugar.

Si la tarea original es inequívocamente de reseñas de ubicaciones, verifica de nuevo si google_maps_reviews ofrece reseñas, qué URL necesita y si la salida sigue cumpliendo los requisitos iniciales. El algoritmo de candidatos solo resuelve similitudes de nombres, sin comprender los objetivos de negocio; las tiendas de aplicaciones comerciales y las reseñas de ubicaciones no son fuentes de datos intercambiables.

422: devuelve la entrada al contrato actual

El significado general de 422 es que el contenido de la petición resulta comprensible, pero las instrucciones que contiene no se pueden procesar. Las aplicaciones deben distinguir además entre campos faltantes, campos desconocidos, enumeraciones no válidas y límites de tamaño. Sus métodos de reparación difieren: si falta una URL, se necesita un destino real; ante un sort desconocido, hay que comprobar los parámetros; si la entrada es demasiado larga, hay que confirmar si se permite dividirla en lugar de eliminar la mitad del material de forma silenciosa.

curl -fsS --max-time 30 \
  'https://api.everyinfra.com/api/v1/social/catalog?platform=douyin' \
  | jq '[.capabilities[] | {
      action, required_params, optional_params, param_meanings, max_limit
    }]'

La implementación actual genera unknown_param para parámetros desconocidos e invalid_value para enumeraciones no compatibles, acompañados de indicaciones procesables. No obstante, los parámetros con el mismo nombre pueden diferir entre distintas acciones, por lo que ninguna tabla de parámetros global sustituye a un contrato específico. Los campos required_params, optional_params y los valores permitidos deben revisarse conjuntamente; el límite general de una lista tampoco constituye una promesa de paginación.

Genera una nueva versión de la petición tras la corrección, conservando el error original y el motivo de la modificación. Aplica las asignaciones automáticamente solo cuando se mantenga el significado original de forma inequívoca; deja las decisiones humanas para múltiples candidatos, falta de objetivos reales, ampliaciones del rango temporal o cambios de modelo. Rellenar los campos ausentes con valores estimados por el modelo no constituye una autorrecuperación segura.

402 y 429: no interpretes los problemas de cuota como limitación de tráfico

EveryInfra usa actualmente 402 quota_exhausted para indicar escasez de cuota; esto constituye un convenio propio del producto y no el significado de negocio genérico 402 de otros servicios. Los problemas de cuota exigen la intervención del responsable de la cuenta; reducir la concurrencia no incrementará el saldo automáticamente, y el cliente tampoco debe recargar ni migrar credenciales por cuenta propia.

429 actúa como señal de limitación de tráfico. Si la respuesta real aporta un Retry-After válido, organízate conforme a este; la ausencia de dicha cabecera no autoriza a reintentar con intensidad de forma inmediata, ni permite inventar un tiempo de recuperación prometido por el servicio. Las políticas de aplicación establecen de forma explícita los intervalos de reintento, las variaciones aleatorias, el número máximo de intentos y el plazo límite total.

La estrategia de limitación de velocidad debe cubrir asimismo a todos los procesos de trabajo que compartan una misma cuota. Si un trabajador individual aplica retroceso por su cuenta pero el resto continúa enviando peticiones, es posible que no se resuelva la congestión real. Esto constituye una recomendación de planificación para la aplicación y no implica que la API coordine múltiples procesos por ti.

Errores 5xx, desconexiones y tareas enviadas: verifica primero el estado de ejecución

Un error 5xx no se puede interpretar simplemente como que no ha ocurrido nada. Es posible que el servicio ya haya aceptado la petición, generado resultados parciales o completado los pasos de facturación sin que el cliente obtuviera la respuesta completa. A falta de garantías explícitas de idempotencia o de pruebas de no ejecución, registra primero un resultado desconocido y comprueba el estado mediante el identificador de petición en lugar de volver a enviar automáticamente la misma solicitud POST.

Prioriza consultar la tarea original cuando obtengas job_id o un punto de consulta facilitado expresamente por el servicio. Deben distinguirse los estados de ejecución, espera de finalización, éxito, fallo y error en la propia consulta; una consulta que devuelva 404 también podría implicar la identidad o el ámbito, por lo que no debería crearse directamente una tarea sustituta. Asegúrate primero de que la consulta usa la identidad correspondiente a la petición original.

Tras un código HTTP 200 sigue siendo necesario comprobar el contenido de negocio. Como MCP añade además capas de JSON-RPC y de errores de herramienta, no puedes usar directamente estrategias basadas solo en el estado REST. Los conjuntos vacíos, los resultados parciales y las respuestas anómalas deben conservar sus propios estados sin agruparse como éxitos ni deducir el cobro final directamente desde el estado del cliente.

El patrón de reintento de Microsoft advierte de forma específica: reintenta exclusivamente fallos susceptibles de recuperación y valora al mismo tiempo la idempotencia de las operaciones junto con la superposición de reintentos en múltiples capas. Si el SDK, las colas y la capa de negocio reintentan de forma independiente, el número real de intentos podría sobrepasar el presupuesto de negocio; una única capa con comprensión del contexto completo debe tomar la decisión en lugar de aplicar un reintento predeterminado en cada nivel.

Un discriminador que solo deriva el tráfico sin ejecutar reintentos

Este ejemplo fuera de línea a nivel de aplicación no pertenece al SDK de EveryInfra. La entrada debe proceder de un registro de intentos REST que ya haya completado el análisis de protocolo; replaySafe debe configurarse según los acuerdos de la interfaz real o pruebas claras de no ejecución, sin permitir que el modelo o el texto del error lo activen por cuenta propia. El parámetro attempts indica la cantidad de intentos realizados.

function nextStep({status, hasJob = false, replaySafe = false,
                   attempts = 1, maxAttempts = 3}) {
  if (status !== null && (!Number.isInteger(status) || status < 100 || status > 599)) {
    throw new Error("invalid HTTP status");
  }
  if (typeof hasJob !== "boolean" || typeof replaySafe !== "boolean"
      || !Number.isSafeInteger(attempts) || attempts < 1
      || !Number.isSafeInteger(maxAttempts) || maxAttempts < 1) {
    throw new Error("invalid decision inputs");
  }
  if (status === 401 || status === 403) return "authorization_review";
  if (status === 402) return "account_review";
  if (hasJob) return "inspect_existing_job";
  if (status === 400 || status === 422) return "revise_request";
  if (status === 429 || status === null || (status >= 500 && status <= 599)) {
    return replaySafe && attempts < maxAttempts
      ? "retry_after_policy_check"
      : "inspect_attempt";
  }
  if (status >= 200 && status < 300) return "validate_delivery";
  return "manual_review";
}

// intento sintético; no contiene llamadas de red.
console.log(nextStep({status: 503}));
console.log(nextStep({status: 429, replaySafe: true, attempts: 3}));
console.log(nextStep({status: 202, hasJob: true}));

Los tres resultados exigen respectivamente comprobar este intento, revisar los intentos tras agotar el presupuesto y consultar la tarea original. retry_after_policy_check tampoco constituye una orden de reenvío inmediato; la capa exterior requiere además comprobar el tiempo de espera, la limitación de velocidad global y el rango de operaciones permitido para el usuario. Si se genera un nuevo intento tras modificar los parámetros, este también computará dentro del presupuesto general de negocio y no se recurrirá a reiniciar contadores para entrar en bucles infinitos.

Validar que la ejecución se detiene es tan importante como comprobar que se recupera

• Autenticación no válida: no accede a otras credenciales ni genera reintentos de negocio.
• Ambofres en candidatos de capacidad: conserva el objetivo original, exige comprobaciones y evita cambios automáticos de producto.
• Aceptada pero con respuesta interrumpida: conserva el intento y la tarea originales sin crear duplicados.
• Fallo continuado tras corregir parámetros: registra la nueva versión y respeta el presupuesto total de intentos.
• Error ajeno a JSON, ausencia de ID de petición o código desconocido: pasa a un tratamiento conservador sin provocar caídas ni falsos éxitos.
• Datos utilizables devueltos sin satisfacer el objetivo de negocio: conserva el estado de entrega y los problemas posteriores sin declarar de forma arbitraria que el saldo se ha restaurado.

Mantén un pequeño conjunto de muestras de errores y reprodúcelo al actualizar SDKs, modificar contratos o cambiar la estrategia de autenticación. Las pruebas de código fuente comprueban el orden esperado, pero el despliegue real requiere además acotar las evidencias in situ de las entradas; registra ambas fechas por separado. No sustituyas la aceptación del negocio autenticado de hoy por capturas antiguas o errores de directorios gratuitos.

El objetivo de la autorrecuperación segura consiste en reducir las interrupciones humanas ante problemas claramente solucionables, permitiendo a la vez que las situaciones que verdaderamente exigen criterio se detengan a tiempo. Siempre que cada paso permita explicar dónde se localizó el error, qué se modificó, si se ejecutó y por qué se autoriza el paso siguiente, las indicaciones de error se convertirán verdaderamente en una ayuda para la integración en lugar de en un activador de reintentos infinitos.