API Error Codes

When a request to the Workflows API fails, the response includes a structured error code in WF_XXXX format:

{
  "detail": "Workflow execution not found",
  "code": "WF_1100"
}

{
  "detail": "Workflow execution not found",
  "code": "WF_1100"
}

For 4xx errors, detail contains a specific message describing what went wrong. For 5xx errors, detail is always "An error occurred" — the actual cause is logged server-side.

WF_1000

Unknown Error · 500 Internal Server Error

A catch-all for errors that don't map to a specific code. If you see this, check server logs or contact the platform team.

WF_1001

Invalid Request · 422 Unprocessable Entity

The request was well-formed but contained invalid data. Currently returned when providing an invalid event ID during a workflow reset — the response includes a valid_reset_events field listing valid alternatives.

{
  "detail": "Invalid event ID for reset",
  "code": "WF_1001",
  "valid_reset_events": [3, 7, 12]
}

{
  "detail": "Invalid event ID for reset",
  "code": "WF_1001",
  "valid_reset_events": [3, 7, 12]
}

WF_1100

Workflow Not Found · 404 Not Found

The workflow execution doesn't exist. This usually means the execution ID is wrong or the workflow has been purged.

Resolution: Verify the execution ID. Check the Workflows Dashboard for the correct ID.

WF_1101

Workflow Already Started · 409 Conflict

A workflow execution with the same ID is already running. Workflow IDs must be unique within a workspace.

Resolution: Use a different execution ID, or wait for the existing execution to complete. If you need to restart it, terminate the running execution first.

WF_1102

Workflow Not Running · 409 Conflict

You attempted an action (signal, query, update, or terminate) on a workflow that is no longer running. The response includes the current workflow status.

{
  "detail": "Workflow not running",
  "code": "WF_1102",
  "status": "COMPLETED"
}

{
  "detail": "Workflow not running",
  "code": "WF_1102",
  "status": "COMPLETED"
}

Resolution: Check the workflow's current status. If it completed or failed, start a new execution instead.

WF_1103

Platform Request Failed · 500 Internal Server Error or 504 Gateway Timeout

The underlying platform RPC call failed. This covers connection issues, timeouts, and unexpected errors. A 504 specifically indicates a deadline exceeded (the operation took too long).

Resolution: Retry the request. If the issue persists, contact the platform team.

WF_1104

Workflow Registration Failed · 500 Internal Server Error

Worker registration failed — the system could not register workflow definitions. This typically indicates a mismatch between workflow specs and version identifiers during worker startup.

Resolution: Check worker logs for registration errors. Verify that workflow definitions are valid and that the worker can reach the API.

WF_1105

Execution Not Found · 500 Internal Server Error

An execution that was expected to exist could not be found. Unlike WF_1100 (which is a 404 for user-facing lookups), this indicates an internal inconsistency — the execution should have existed at this point in the flow.

Resolution: This is an internal error. If it persists, report it to the platform team.

WF_1200

Schedule Failed · 422 / 500 / 503

Schedule creation or management failed. The HTTP status varies by cause:

Resolution: For 422, check your cron expression and input payload size. For 503, retry after a few seconds. For 500, check server logs.

WF_1201

Schedule Not Found · 404 Not Found

The schedule ID doesn't exist. It may have already been deleted or never created.

Resolution: List existing schedules to find the correct ID.

WF_1300

Platform Client Creation Failed · 500 Internal Server Error

The system failed to construct a platform client, usually due to configuration issues (bad address, invalid credentials).

Resolution: Check connection configuration (host, port, TLS settings).

WF_1301

Platform Initialization Failed · 500 Internal Server Error

Search attribute registration failed during platform initialization. This happens during system startup.

Resolution: Contact the platform team if this persists.

WF_1302

Payload Encoding Required · 500 Internal Server Error

Payload encoding is enforced but the input data was not encoded. This occurs in deployments where payload encoding is enabled (typically hybrid deployments where data must stay encrypted).

Resolution: Ensure your client is using the payload codec. See payload encoding documentation for details.

WF_1400

Streaming Error · 500 Internal Server Error

A streaming operation failed — connection, publishing, or reading from a stream.

Resolution: Check streaming connectivity. See Streaming for configuration details.

WF_1500

Trace Error · 500 Internal Server Error

Failed to retrieve or parse traces from the Tempo backend. This can mean missing spans, malformed trace data, or connectivity issues with the trace provider.

Resolution: Check Tempo/tracing backend health. If traces are missing, the workflow may not have emitted spans yet — wait and retry.

WF_1600

Event Store Error · 500 Internal Server Error

A database consistency error in the event store, typically when an expected event can't be found after a conflict.

Resolution: This is an internal error. Retry the operation. If it persists, report it to the platform team.

The Python SDK (mistralai-workflows) has its own set of error codes for worker-side errors (invalid workflow definitions, activity configuration issues, etc.). These are different from the API error codes above and are documented in the Workflows Exception guide.