Códigos de error

Los errores de la API de Fetch Hive incluyen un message legible para humanos, un error_code estable y error como alias de compatibilidad para el mismo mensaje. Las respuestas más antiguas de plan y límite de tasa también pueden incluir code; trata code como un alias obsoleto y lee error_code primero. Fetch Hive devuelve mensajes de error localizados según el idioma configurado en tu cuenta. Los códigos de error son identificadores estables en los que puedes confiar en tu código cliente.

Endpoint del catálogo

Usa GET /v1/error_codes para recuperar el catálogo público. El endpoint no requiere autenticación porque devuelve metadatos estáticos del contrato de la API. Pasa ?locale=es para solicitar el texto del catálogo en español; los idiomas no soportados o no disponibles recurren al inglés.

{
  "locale": "en",
  "default_field": "error_code",
  "compatibility_aliases": ["code"],
  "codes": [
    {
      "code": "model_deprecated",
      "status": 422,
      "field": "error_code",
      "message_key": "errors.codes.model_deprecated",
      "message": "The selected model \"%{model}\" is no longer available. Choose a current model and try again.",
      "field_aliases": [],
      "category": "runtime",
      "client_action_key": "errors.client_actions.model_deprecated",
      "client_action": "Choose an active model and retry."
    }
  ]
}

Forma del error en JSON

{
  "error": "The selected model \"old-model\" is no longer available. Choose a current model and try again.",
  "message": "The selected model \"old-model\" is no longer available. Choose a current model and try again.",
  "error_code": "model_deprecated"
}

Forma del error en SSE

Los endpoints de streaming envían errores como Server-Sent Events con type: "error".

{
  "type": "error",
  "error": "Provider request failed",
  "message": "Provider request failed",
  "error_code": "provider_error",
  "error_type": "provider_error",
  "status_code": 502
}

Códigos

Código	Campo	Estado	Significado	Acción del cliente
`model_deprecated`	`error_code`	`422`	El prompt guardado, agente, paso de flujo de trabajo, despliegue o modelo de respaldo ya no está disponible.	Elige un modelo activo y reintenta.
`personal_model_missing_credentials`	`error_code`	`422`	Una ejecución de modelo personal necesita credenciales del proveedor que no están conectadas.	Conecta las credenciales o cambia a un modelo alojado/actual.
`personal_model_invalid_credentials`	`error_code`	`422`	Las credenciales del proveedor estaban presentes pero fueron rechazadas por el proveedor.	Vuelve a conectar o rota la credencial del proveedor.
`insufficient_hosted_llm_credits`	`error_code`	`402`	El espacio de trabajo no tiene suficientes créditos de LLM alojado para la ejecución.	Agrega créditos, actualiza el plan o usa una clave de proveedor personal.
`account_credit_cap_reached`	`error_code`	`422`	La cuenta alcanzó su tope general de créditos.	Actualiza el plan o espera más créditos antes de reintentar.
`asset_storage_limit_reached`	`error_code`	`402`	El espacio de trabajo alcanzó su límite de almacenamiento de activos.	Elimina activos o actualiza el plan del espacio de trabajo.
`vision_not_supported`	`error_code`	`422`	El modelo seleccionado no puede procesar entradas de imagen.	Selecciona un modelo con capacidad de visión o elimina las entradas de imagen.
`workflow_step_limit_reached`	`error_code`	`402`	El flujo de trabajo alcanzó el límite de pasos del plan.	Elimina pasos o actualiza el plan.
`workspace_limit_reached`	`error_code`	`402`	La cuenta alcanzó el límite de espacios de trabajo del plan.	Elimina un espacio de trabajo o actualiza el plan.
`api_rate_limit_exceeded`	`error_code`	`429`	La clave de API alcanzó su tope diario de solicitudes.	Reintenta después del reinicio o actualiza el plan.
`log_range_limit_exceeded`	`error_code`	`402`	El rango de registros solicitado es mayor que la ventana permitida.	Reduce el rango de fechas.
`experiment_run_result_limit_exceeded`	`error_code`	`422`	Una ejecución de experimento crearía más celdas de resultado de las permitidas por el plan actual.	Reduce filas del dataset o candidatos activos, o actualiza el plan.
`experiment_candidate_type_unsupported`	`error_code`	`422`	El tipo de candidato de experimento no es compatible con experimentos solo de prompts.	Usa un candidato de prompt del panel o prompt desplegado.
`experiment_run_unsupported_candidates`	`error_code`	`422`	Una ejecución de experimento incluye candidatos activos que no se pueden ejecutar en experimentos solo de prompts.	Archiva los candidatos no compatibles y reintenta.
`experiment_dataset_row_limit_exceeded`	`error_code`	`422`	Una versión de dataset superaría el límite de 10.000 filas.	Reduce las filas del CSV y reintenta.
`experiment_run_start_failed`	`error_code`	`503`	Fetch Hive no pudo iniciar el workflow del experimento después de crear el registro de ejecución.	Reintenta la ejecución; contacta a soporte si persiste.
`iteration_limit_exceeded`	`error_code`	`422`	Una iteración de flujo de trabajo excedió el número de bucles permitido.	Reduce el tamaño de la entrada o la cantidad de iteraciones.
`internal_server_error`	`error_code`	`500`	Fetch Hive encontró un error interno inesperado.	Reintenta más tarde; contacta a soporte si persiste.
`too_many_requests`	`error_code`	`429`	Un proveedor o Fetch Hive rechazó la solicitud debido al límite de tasa.	Aplica backoff y reintenta.
`concurrency_limit_reached`	`error_code`	`429`	La cuenta alcanzó su límite de concurrencia de flujos de trabajo activos.	Reintenta más tarde o usa entrega por callback.
`validation_error`	`error_code`	`400`/`422`	Los parámetros de la solicitud no eran válidos antes de iniciar la ejecución.	Corrige el cuerpo o los parámetros de consulta de la solicitud.
`unsupported_provider`	`error_code`	`400`	El proveedor configurado no es compatible con esa ruta de runtime.	Selecciona un proveedor/modelo soportado.
`database_error`	`error_code`	`500`	Fetch Hive no pudo completar la operación solicitada.	Reintenta más tarde; contacta a soporte si persiste.
`config_error`	`error_code`	`500`	La configuración de runtime estaba ausente o era inválida.	Contacta a soporte.
`provider_error`	`error_code`	`502`	Un proveedor de modelos rechazó o falló la solicitud.	Verifica el estado/entrada del proveedor y reintenta.
`agent_completion_persistence_failed`	`error_code`	`503`	Fetch Hive no pudo persistir una completación del agente después de la ejecución del proveedor.	Reintenta la solicitud; contacta a soporte si persiste.
`upstream_request_failed`	`error_code`	`502`/`504`	Fetch Hive no pudo obtener una respuesta exitosa de un servicio ascendente.	Reintenta más tarde; contacta a soporte si persiste.
`workflow_enqueue_failed`	`error_code`	`500`	No se pudo encolar una ejecución de flujo de trabajo.	Reintenta la ejecución del flujo de trabajo.
`not_found`	`error_code`	`404`	El recurso solicitado no fue encontrado para la cuenta autenticada.	Verifica el identificador y el contexto de la cuenta.
`resource_not_found`	`error_code`	`404`	No se encontró el recurso solicitado.	Verifica el identificador y el contexto de la cuenta.
`invalid_access`	`error_code`	`401`	La solicitud del panel o pública no está autenticada para la cuenta solicitada.	Inicia sesión nuevamente y reintenta.
`unauthorized`	`error_code`	`401`	La solicitud carece de autorización válida.	Inicia sesión nuevamente y reintenta.
`forbidden`	`error_code`	`403`	El llamador está autenticado pero no tiene permitido realizar la acción.	Usa una cuenta con acceso o contacta a un administrador.
`invalid_api_key`	`error_code`	`401`	Una solicitud global o autenticada por clave de API usó una clave inválida.	Verifica la clave de API y reintenta.
`invalid_request`	`error_code`	`400`	Un campo de la solicitud es inválido.	Corrige la solicitud y reintenta.
`missing_required_field`	`error_code`	`422`	Falta un campo requerido en la solicitud.	Proporciona el campo requerido y reintenta.
`missing_required_header`	`error_code`	`400`	Falta un encabezado requerido en la solicitud.	Envía el encabezado requerido y reintenta.
`validation_failed`	`error_code`	`422`	La validación de la solicitud falló; los detalles se devuelven en `errors` o `details`.	Corrige los campos resaltados y reintenta.
`payment_failed`	`error_code`	`422`	Falló un flujo de pago de Stripe.	Verifica el método de pago y reintenta.
`billing_configuration_missing`	`error_code`	`422`	Un plan o ruta de facturación solicitada carece de configuración de Stripe del lado del servidor.	Contacta a soporte.
`stripe_customer_creation_failed`	`error_code`	`422`	Fetch Hive no pudo crear ni cargar el cliente de Stripe para la cuenta.	Reintenta más tarde; contacta a soporte si persiste.
`promotion_code_invalid`	`error_code`	`200`	Un código de descuento está ausente, es inválido, ha expirado o fue rechazado por Stripe.	Verifica el código de descuento y reintenta.
`archive_restore_conflict`	`error_code`	`409`	Ya hay una restauración de archivo en ejecución para la cuenta.	Espera a que termine la restauración existente antes de reintentar.
`completion_resolution_failed`	`error_code`	`500`	Fetch Hive no pudo resolver una completación a su URL del panel.	Reintenta más tarde; contacta a soporte si persiste.
`integration_connection_failed`	`error_code`	`502`	No se pudo iniciar ni sincronizar la conexión de una integración.	Vuelve a conectar la integración y reintenta.
`webhook_signature_invalid`	`error_code`	`400`	No se pudo verificar la firma de un webhook.	Verifica el secreto de firma del webhook y reintenta.
`webhook_signature_not_configured`	`error_code`	`500`	Falta un secreto de firma de webhook en el servidor.	Configura el secreto de firma del webhook antes de reintentar.
`webhook_payload_invalid`	`error_code`	`400`	No se pudo analizar la carga útil del webhook.	Envía una carga útil de webhook válida.
`mcp_connection_failed`	`error_code`	`422`	Falló la prueba de un servidor MCP del espacio de trabajo.	Verifica la URL del servidor MCP, la autenticación y el formato de respuesta.
`unsupported_resource_type`	`error_code`	`400`	El tipo de recurso solicitado no es compatible.	Usa un tipo de recurso soportado.

Para workflow_step_limit_reached, workspace_limit_reached, api_rate_limit_exceeded y log_range_limit_exceeded, las respuestas también pueden incluir code con el mismo valor para clientes más antiguos.

​Códigos de error

​Endpoint del catálogo

​Forma del error en JSON

​Forma del error en SSE

​Códigos

Códigos de error

Endpoint del catálogo

Forma del error en JSON

Forma del error en SSE

Códigos