> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.ripio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cancel Order via WebSocket

> Cancel an active trading order via WebSocket API

Cancels an active trading order via WebSocket API. You can cancel by order ID or external ID.

## Request

<ParamField body="id" type="string" required>
  Unique request identifier for correlation
</ParamField>

<ParamField body="method" type="string" required>
  WebSocket API method. Must be `order.cancel`
</ParamField>

<ParamField body="params" type="object" required>
  Request parameters containing authentication and order cancellation details

  <Expandable title="Authentication">
    <ParamField body="params.api_token" type="string" required>
      API Token for authentication
    </ParamField>

    <ParamField body="params.timestamp" type="integer" required>
      Timestamp in milliseconds (UTC)
    </ParamField>

    <ParamField body="params.signature" type="string" required>
      HMAC SHA256 signature of the request
    </ParamField>
  </Expandable>

  <Expandable title="Cancellation Parameters">
    <ParamField body="params.id" type="string">
      Order ID to cancel. Use either `id` or `external_id`, not both.
    </ParamField>

    <ParamField body="params.external_id" type="string">
      External Order ID to cancel. Use either `id` or `external_id`, not both.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  You must provide either `id` or `external_id` in the params, but not both. The order must be active (open or partially executed) to be canceled.
</Note>

## Response

<ResponseField name="id" type="string">
  Request identifier for correlation
</ResponseField>

<ResponseField name="status" type="integer">
  HTTP status code (200 for success)
</ResponseField>

<ResponseField name="result" type="object">
  Canceled order details object

  <Expandable title="Canceled Order Details">
    <ResponseField name="id" type="string">
      Order identifier
    </ResponseField>

    <ResponseField name="create_date" type="string">
      Order creation datetime (ISO 8601 format)
    </ResponseField>

    <ResponseField name="update_date" type="string">
      Order cancellation datetime (ISO 8601 format)
    </ResponseField>

    <ResponseField name="executed_amount" type="number">
      Amount that was executed before cancellation
    </ResponseField>

    <ResponseField name="remaining_amount" type="number">
      Amount that remained when order was canceled
    </ResponseField>

    <ResponseField name="remaining_value" type="number">
      Value that remained when order was canceled
    </ResponseField>

    <ResponseField name="requested_amount" type="number">
      Total amount that was requested
    </ResponseField>

    <ResponseField name="requested_value" type="number">
      Total value that was requested
    </ResponseField>

    <ResponseField name="total_value" type="number">
      Total value of the order
    </ResponseField>

    <ResponseField name="status" type="string">
      Order status: `canceled`
    </ResponseField>

    <ResponseField name="type" type="string">
      Order type (e.g., `limit`, `market`, `stop_limit`)
    </ResponseField>

    <ResponseField name="price" type="number">
      Order price (if applicable)
    </ResponseField>

    <ResponseField name="pair" type="string">
      Trading pair code
    </ResponseField>

    <ResponseField name="external_id" type="string">
      External order identifier
    </ResponseField>
  </Expandable>
</ResponseField>

## Error Response

<ResponseField name="id" type="string">
  Request identifier for correlation
</ResponseField>

<ResponseField name="status" type="integer">
  HTTP error status code
</ResponseField>

<ResponseField name="result" type="null">
  Always null for error responses
</ResponseField>

<ResponseField name="error" type="object">
  Error details object

  <Expandable title="Error Details">
    <ResponseField name="error_code" type="integer">
      Error code (e.g., 40401 for order not found, 40408 for order already canceled/executed)
    </ResponseField>

    <ResponseField name="message" type="string">
      Human-readable error message
    </ResponseField>
  </Expandable>
</ResponseField>

## Examples

<CodeGroup>
  ```json Cancel Order by ID theme={null}
  {
    "id": "req-003",
    "method": "order.cancel",
    "params": {
      "api_token": "your-api-token",
      "timestamp": 1634567890000,
      "signature": "calculated-signature",
      "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F"
    }
  }
  ```

  ```json Cancel Order by External ID theme={null}
  {
    "id": "req-004",
    "method": "order.cancel",
    "params": {
      "api_token": "your-api-token",
      "timestamp": 1634567890000,
      "signature": "calculated-signature",
      "external_id": "my-order-123"
    }
  }
  ```
</CodeGroup>

## Success Response Example

```json theme={null}
{
  "id": "req-003",
  "status": 200,
  "result": {
    "id": "7155ED34-9EC4-4733-8B32-1E4319CB662F",
    "create_date": "2024-03-27T13:27:19.853Z",
    "update_date": "2024-03-27T13:30:45.123Z",
    "executed_amount": 0,
    "remaining_amount": 0.001,
    "remaining_value": 100,
    "requested_amount": 0.001,
    "requested_value": 100,
    "total_value": 100,
    "status": "canceled",
    "type": "limit",
    "price": 100000,
    "pair": "BTC_BRL",
    "external_id": "my-order-123"
  }
}
```

## Error Response Examples

### Order Not Found

```json theme={null}
{
  "id": "req-003",
  "status": 404,
  "result": null,
  "error": {
    "error_code": 40401,
    "message": "Order not found."
  }
}
```

### Order Already Canceled or Fully Executed

```json theme={null}
{
  "id": "req-003",
  "status": 400,
  "result": null,
  "error": {
    "error_code": 40408,
    "message": "Cannot cancel an already canceled or fully executed order."
  }
}
```

## Usage Notes

* **Order ID vs External ID**: Provide either the internal order ID returned from order creation or the external ID you assigned when creating the order. Do not provide both.
* **Order Status**: Only active orders (status `open` or `executed_partially`) can be canceled.
* **Already Canceled Orders**: Attempting to cancel an already canceled or fully executed order will result in an error.
* **Execution Guarantee**: If part of the order was already executed before cancellation, you will receive the executed amount in the response.
* **Request Correlation**: Always use a unique `id` in each request for proper correlation with responses.

## Common Error Codes

| Error Code | Message                                                   | Description                                      |
| ---------- | --------------------------------------------------------- | ------------------------------------------------ |
| 40401      | Order not found                                           | The order ID or external ID does not exist       |
| 40408      | Cannot cancel an already canceled or fully executed order | The order is no longer active                    |
| 40011      | Invalid signature                                         | The signature is invalid or timestamp is expired |
| 40010      | Missing required parameters                               | Required parameters are missing from the request |