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

# Timing & Retries

> Controlling execution timing and handling failures

Web automation requires careful timing. Pages load at different speeds, elements appear dynamically, and networks can be slow.

## Timing Controls

| Level                  | Properties                                                                       |
| ---------------------- | -------------------------------------------------------------------------------- |
| **Automation**         | `max_retries`                                                                    |
| **Action Node**        | `before_sleep_time`, `end_sleep_time`, `expect_new_tab`, `max_new_tab_wait_time` |
| **Interaction Action** | `max_tries`, `max_timeout_seconds_per_try`                                       |

## Sleep Times

### before\_sleep\_time

Wait **before** executing the action. Use when page needs to load or settle.

```json theme={null}
{
  "type": "action_node",
  "interaction_action": { ... },
  "before_sleep_time": 3.0
}
```

### end\_sleep\_time

Wait **after** action completes. Use when subsequent actions depend on this action's effects.

```json theme={null}
{
  "type": "action_node",
  "interaction_action": { ... },
  "end_sleep_time": 2.0
}
```

### Default Values

| Action Type | `before_sleep_time` | `end_sleep_time` |
| ----------- | ------------------- | ---------------- |
| Interaction | `0.0`               | `1.0`            |
| Extraction  | `3.0`               | `0.0`            |
| Assertion   | `0.0`               | `0.0`            |
| 2FA         | `0.0`               | `0.0`            |

<Info>
  Sleep times must be between 0 and 10 seconds.
</Info>

***

## Automation-Level Retries

`max_retries` on the automation reruns the **entire automation** when an unexpected error occurs (e.g. browser crash, network failure).

| Property      | Type  | Default | Description                                               |
| ------------- | ----- | ------- | --------------------------------------------------------- |
| `max_retries` | `int` | `0`     | Total run attempts. `1` = no retry, `1` = one retry, etc. |

```json theme={null}
{
  "url": "https://example.com",
  "max_retries": 3,
  "nodes": [ ... ]
}
```

<Info>
  `AssertionError` failures (e.g. failed assertions) are **never** retried regardless of `max_retries`. Retries only apply to unexpected runtime errors.
</Info>

***

## Element-Level Retry Configuration

Control how Optexity retries finding elements.

| Property                      | Type    | Default | Description            |
| ----------------------------- | ------- | ------- | ---------------------- |
| `max_tries`                   | `int`   | `10`    | Maximum retry attempts |
| `max_timeout_seconds_per_try` | `float` | `1.0`   | Timeout per attempt    |

```json theme={null}
{
  "interaction_action": {
    "max_tries": 15,
    "max_timeout_seconds_per_try": 2.0,
    "click_element": { ... }
  }
}
```

### How Retries Work

1. Attempt to find element using `command` or `xpath`
2. If not found within timeout, retry
3. After all tries exhausted, use AI with `prompt_instructions`
4. If AI can't find it, action fails

<Tip>
  Increase `max_tries` rather than timeout per try. This finds elements faster when they appear while still handling slow pages.
</Tip>

***

## Handling New Tabs

### expect\_new\_tab

Set when action opens a new browser tab:

```json theme={null}
{
  "type": "action_node",
  "interaction_action": {
    "click_element": {
      "command": "get_by_role(\"link\", name=\"Open Report\")"
    }
  },
  "expect_new_tab": true
}
```

When `expect_new_tab=True`:

* `max_new_tab_wait_time` automatically set to `10.0`
* Automation waits for new tab
* Focus switches to new tab

***

## Common Patterns

### Slow-Loading Pages

```json theme={null}
{
  "type": "action_node",
  "interaction_action": {
    "click_element": {
      "command": "get_by_role(\"button\", name=\"Search\")"
    }
  },
  "end_sleep_time": 5.0
}
```

### Dynamic AJAX Content

```json theme={null}
{
  "type": "action_node",
  "interaction_action": {
    "max_tries": 15,
    "max_timeout_seconds_per_try": 1.0,
    "click_element": {
      "command": "get_by_text(\"Results loaded\")"
    }
  },
  "before_sleep_time": 2.0
}
```

### Optional Elements

```json theme={null}
{
  "type": "action_node",
  "interaction_action": {
    "max_tries": 3,
    "click_element": {
      "command": "get_by_role(\"button\", name=\"Dismiss\")",
      "skip_prompt": true,
      "assert_locator_presence": true
    }
  }
}
```

***

## Troubleshooting

| Symptom                | Likely Cause              | Solution                        |
| ---------------------- | ------------------------- | ------------------------------- |
| "Element not found"    | Page not loaded           | Increase `before_sleep_time`    |
| Clicking wrong element | Page still loading        | Increase `before_sleep_time`    |
| Missing extracted data | Content not rendered      | Increase wait before extraction |
| Next action fails      | Previous effect not ready | Increase `end_sleep_time`       |
| Random failures        | Race conditions           | Increase retries and timeouts   |

***

## Best Practices

| Practice               | Recommendation                             |
| ---------------------- | ------------------------------------------ |
| Start conservative     | Use longer waits initially, optimize later |
| Use defaults           | Let action-type defaults handle most cases |
| Wait before extraction | Ensure page stability                      |
| Wait after navigation  | Give pages time to load                    |
| Increase retries       | Prefer more tries over longer timeouts     |