WorkflowsException

Workflows provides a structured exception class, WorkflowsException, for consistent error handling across workflows and activities.

When to use

When to use

Raise WorkflowsException for expected, structured errors that callers (other workflows, activities, or API consumers) need to inspect and react to — invalid input, business-rule violations, known failure modes of an external service. The structured code and HTTP status make these errors recognizable across the system and surfaceable in API responses.

For unexpected errors (a KeyError, an httpx.ConnectError, a panic in a third-party library), let the exception propagate. The platform will record the error in the activity/workflow event history, apply your retry policy, and ultimately mark the execution as failed if retries are exhausted. Wrapping every exception in WorkflowsException adds noise without information.

Overview

Overview

WorkflowsException provides:

  • Structured error codes via the ErrorCode enum
  • HTTP status code mapping
  • Serialization to JSON responses
  • Factory methods for common error scenarios
Basic usage

Basic usage

import asyncio
import http
import mistralai.workflows as workflows
from mistralai.workflows.exceptions import WorkflowsException, ErrorCode
from pydantic import BaseModel


@workflows.activity()
async def validate_input(value: str) -> str:
    if not value:
        raise WorkflowsException(
            code=ErrorCode.INVALID_ARGUMENTS_ERROR,
            message="Input value cannot be empty",
            status=http.HTTPStatus.BAD_REQUEST,
        )
    return f"valid:{value}"


class Input(BaseModel):
    value: str


@workflows.workflow.define(name="exception_workflow")
class ExceptionWorkflow:
    @workflows.workflow.entrypoint
    async def run(self, params: Input) -> str:
        return await validate_input(params.value)


async def main():
    result = await workflows.execute_workflow(
        ExceptionWorkflow,
        params=Input(value="hello"),
    )
    print(result)

    try:
        await workflows.execute_workflow(
            ExceptionWorkflow,
            params=Input(value=""),
        )
    except WorkflowsException as e:
        print(f"code:    {e.code}")
        print(f"message: {e.message}")
        print(f"status:  {e.status}")
Constructor Parameters

Constructor Parameters

ParameterTypeDefaultDescription
messagestrrequiredHuman-readable error message
statusHTTPStatusINTERNAL_SERVER_ERRORHTTP status code
codeErrorCodeEXECUTION_ERRORStructured error code
typestr"invalid_request_error"Top-level error type string surfaced in API responses (matches the type field used by other Mistral APIs). Most callers can leave this default.
Error Codes

Error Codes

The ErrorCode enum provides structured error codes organized by category:

General Errors (40xx)

General Errors (40xx)

CodeDescription
execution_errorGeneral execution error
platform_errorPlatform-related error
platform_service_errorPlatform service error
platform_connection_errorConnection to platform failed
platform_client_creation_errorFailed to create platform client
search_attributes_creation_errorFailed to create search attributes
Activity Errors (41xx)

Activity Errors (41xx)

CodeDescription
activity_definition_errorActivity incorrectly defined
activity_not_found_errorActivity not found
invalid_arguments_errorInvalid arguments provided
activity_not_module_levelActivity must be at module level
tool_argument_errorTool argument error
rate_limit_errorRate limit exceeded
Workflow Errors (42xx)

Workflow Errors (42xx)

CodeDescription
workflow_definition_errorWorkflow incorrectly defined
workflow_description_errorWorkflow description error
workflow_already_startedWorkflow already running
workflow_not_foundWorkflow not found
invalid_params_errorInvalid parameters
workflow_timeout_errorWorkflow timed out
workflow_signal_definition_errorSignal incorrectly defined
workflow_update_definition_errorUpdate incorrectly defined
workflow_query_errorFail to query a workflow
Worker Errors (43xx)

Worker Errors (43xx)

CodeDescription
worker_registration_errorWorker registration failed
worker_runtime_config_errorWorker runtime configuration error
Durable Agent Errors (44xx)

Durable Agent Errors (44xx)

CodeDescription
agent_execution_errorAgent Execution Error
Infrastructure Errors (45xx)

Infrastructure Errors (45xx)

CodeDescription
workspace_already_usedWorkspace already in use
in_memory_cache_errorIn-memory cache error
rejected_query_errorQuery was rejected
unserializable_payload_errorPayload cannot be serialized
blob_storage_config_errorBlob storage configuration error