> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

# FailTurn

# Package: containersApp

# Namespace: ContainersChat

# Method link: https://dev.wix.com/docs/api-reference/mobile/containers-app/containers-chat/fail-turn.md

## Introduction

Marks the in-flight assistant turn as failed.

---

## REST API

### Schema

```
 Method: failTurn
 Description: Marks the in-flight assistant turn as failed.
 URL: https://www.wixapis.com/containers/chat/v1/conversations/{conversationId}/fail-turn
 Method: POST
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  correlationId
 Method parameters: 
   param name: correlationId | type: correlationId | description: GUID of the user message this turn answers. | required: true | validation: format GUID
   param name: error | type: error | description: Human-readable failure reason.  | validation: maxLength 5000
 Return type: FailTurnResponse
  - name: message | type: Message | description: Failed assistant message.  
     - name: id | type: string | description: Message GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision, incremented on each update; used for optimistic concurrency.  | read-only: true | validation: format int64
     - name: createdDate | type: string | description: Date and time the Message was created.  | read-only: true | validation: format date-time
     - name: updatedDate | type: string | description: Date and time the Message was last updated.  | read-only: true | validation: format date-time
     - name: conversationId | type: string | description: GUID of the conversation this Message belongs to. Set on create; immutable afterwards.  | validation: format GUID, immutable
     - name: inReplyToId | type: string | description: For an assistant turn, the GUID of the user Message it answers.  | validation: format GUID
     - name: role | type: Role | description: Who authored the turn (user / assistant / tool).  
         - enum: USER, ASSISTANT, TOOL
     - name: status | type: MessageStatus | description: Lifecycle status of the turn (WORKING -> DONE / ERROR).  
         - enum: WORKING, DONE, ERROR
     - name: parts | type: array<MessagePart> | description: Ordered content parts making up the turn.  | validation: maxItems 200
        - name: type | type: PartType | description: Kind of content carried by this part.  
             - enum: TEXT, CODE, IMAGE, FILE, TOOL_CALL
        - name: text | type: string | description: Inline textual content (used by TEXT / CODE / TOOL_CALL parts).  | validation: maxLength 100000
        - name: uri | type: string | description: Reference to external content (used by IMAGE / FILE parts).  | validation: maxLength 2000
     - name: tasks | type: array<Task> | description: Live work breakdown shown as a checklist on an in-flight assistant turn.  | validation: maxItems 200
        - name: id | type: string | description: Client-supplied task GUID, unique within the turn.  | validation: maxLength 100
        - name: title | type: string | description: Human-readable task description.  | validation: maxLength 500
        - name: status | type: TaskStatus | description: Current status of the task.  
             - enum: PENDING, IN_PROGRESS, DONE_TASK, FAILED
     - name: jobId | type: string | description: GUID of the build job backing this turn, when applicable.  | validation: format GUID
     - name: versionId | type: string | description: Opaque code version produced by an edit turn, when applicable.  | validation: format GUID
     - name: followUpQuestions | type: array<string> | description: Optional suggested next prompts attached to an assistant turn (planning & build). No entity of its own — carried on the message and set on DONE.  | validation: maxItems 50, maxLength 4000
     - name: followUpQuestionOptions | type: array<FollowUpQuestion> | description: Structured follow-up questions with selectable answer options. Superseding follow_up_questions; that field is kept and populated in parallel for callers that have not migrated to this one.  | validation: maxItems 4
        - name: question | type: string | description: The question text.  | validation: maxLength 4000
        - name: options | type: array<string> | description: Selectable answer options for this question.  | validation: maxItems 10, maxLength 200


```

### Examples

### Fail Turn
Marks the in-flight assistant turn as failed.

```curl
curl -X POST \
  'https://www.wixapis.com/containers/chat/v1/conversations/1f5b2c8e-9a3d-4c21-8b77-2d2f6e0a9c10/fail-turn' \
  -H 'Authorization: <AUTH>' \
  -H 'Content-Type: application/json' \
  -d '{
    "correlationId": "d5e9f3c2-1a4b-4c8d-9e7f-2b3c4d5e6f70",
    "error": "The coding agent encountered an unexpected error and could not complete the request."
  }'
```

---

## JavaScript SDK

### Schema

```
 Method: wixClientAdmin.containers.chat.failTurn(conversationId, correlationId, options)
 Description: Marks the in-flight assistant turn as failed.
 # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present.
 Required parameters:  conversationId, correlationId
 Method parameters: 
   param name: conversationId | type: string | description: Conversation GUID. | required: true | validation: format GUID
   param name: correlationId | type: string | description: GUID of the user message this turn answers. | required: true | validation: format GUID
   param name: options | type: FailTurnOptions  none  
        - name: error | type: string | description: Human-readable failure reason.  | validation: maxLength 5000
 Return type: PROMISE<FailTurnResponse>
  - name: message | type: Message | description: Failed assistant message.  
     - name: _id | type: string | description: Message GUID.  | read-only: true | validation: format GUID
     - name: revision | type: string | description: Revision, incremented on each update; used for optimistic concurrency.  | read-only: true | validation: format int64
     - name: _createdDate | type: Date | description: Date and time the Message was created.  | read-only: true 
     - name: _updatedDate | type: Date | description: Date and time the Message was last updated.  | read-only: true 
     - name: conversationId | type: string | description: GUID of the conversation this Message belongs to. Set on create; immutable afterwards.  | validation: format GUID, immutable
     - name: inReplyToId | type: string | description: For an assistant turn, the GUID of the user Message it answers.  | validation: format GUID
     - name: role | type: Role | description: Who authored the turn (user / assistant / tool).  
         - enum: USER, ASSISTANT, TOOL
     - name: status | type: MessageStatus | description: Lifecycle status of the turn (WORKING -> DONE / ERROR).  
         - enum: WORKING, DONE, ERROR
     - name: parts | type: array<MessagePart> | description: Ordered content parts making up the turn.  | validation: maxItems 200
        - name: type | type: PartType | description: Kind of content carried by this part.  
             - enum: TEXT, CODE, IMAGE, FILE, TOOL_CALL
        - name: text | type: string | description: Inline textual content (used by TEXT / CODE / TOOL_CALL parts).  | validation: maxLength 100000
        - name: uri | type: string | description: Reference to external content (used by IMAGE / FILE parts).  | validation: maxLength 2000
     - name: tasks | type: array<Task> | description: Live work breakdown shown as a checklist on an in-flight assistant turn.  | validation: maxItems 200
        - name: _id | type: string | description: Client-supplied task GUID, unique within the turn.  | validation: maxLength 100
        - name: title | type: string | description: Human-readable task description.  | validation: maxLength 500
        - name: status | type: TaskStatus | description: Current status of the task.  
             - enum: PENDING, IN_PROGRESS, DONE_TASK, FAILED
     - name: jobId | type: string | description: GUID of the build job backing this turn, when applicable.  | validation: format GUID
     - name: versionId | type: string | description: Opaque code version produced by an edit turn, when applicable.  | validation: format GUID
     - name: followUpQuestions | type: array<string> | description: Optional suggested next prompts attached to an assistant turn (planning & build). No entity of its own — carried on the message and set on DONE.  | validation: maxItems 50, maxLength 4000
     - name: followUpQuestionOptions | type: array<FollowUpQuestion> | description: Structured follow-up questions with selectable answer options. Superseding follow_up_questions; that field is kept and populated in parallel for callers that have not migrated to this one.  | validation: maxItems 4
        - name: question | type: string | description: The question text.  | validation: maxLength 4000
        - name: options | type: array<string> | description: Selectable answer options for this question.  | validation: maxItems 10, maxLength 200


```

### Examples

### Mark an in-flight assistant turn as failed
```javascript
import { chat } from "@wix/containers";

async function failTurn() {
  const response = await chat.failTurn(
    "1f5b2c8e-9a3d-4c21-8b77-2d2f6e0a9c10",
    "d5e9f3c2-1a4b-4c8d-9e7f-2b3c4d5e6f70",
    {
      error: "Build job failed: could not resolve component dependency.",
    },
  );
}

/* Promise resolves to:
 * {
 *   "_id": "f3a7b2c1-8e4d-4f9a-bc12-3d4e5f6a7b8c",
 *   "conversationId": "1f5b2c8e-9a3d-4c21-8b77-2d2f6e0a9c10",
 *   "inReplyToId": "d5e9f3c2-1a4b-4c8d-9e7f-2b3c4d5e6f70",
 *   "role": "ASSISTANT",
 *   "status": "ERROR",
 *   "parts": [],
 *   "revision": 1,
 *   "_createdDate": "2026-07-29T09:02:05.000Z",
 *   "_updatedDate": "2026-07-29T09:02:30.000Z"
 * }
 */

```

### failTurn (self-hosted)
Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md).

```javascript
import { createClient } from '@wix/sdk';
import { chat } from '@wix/containers';
// Import the auth strategy for the relevant access type
// Import the relevant host module if needed

const myWixClient = createClient ({
  modules: { chat },
  // Include the auth strategy and host as relevant
});


async function failTurn(conversationId,correlationId,options) {
  const response = await myWixClient.chat.failTurn(conversationId,correlationId,options);
};
```

---