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

# Error & Retries Mechanism

> Comprehensive guide to handling API errors and retry mechanisms

### Why Retries Matter

Workflows can sometimes encounter interruptions due to **paused**, **stopped**, or **shutdown** statuses.
Understanding **why retries are important**, **when to retry**, and **how to do it effectively** is essential for maintaining smooth operations and minimizing delays.

### **Account Rotation: A Smoother Process**

Using **account rotation** for search and enrichment actions ensures retries are seamless and done on our end.

Here’s how it works:

* When an account becomes **invalid** or reaches its **daily limit**, the system automatically switches to another available account.
* If no valid accounts remain, the system uses the account with the **limit reached** and schedules the job to retry automatically once it’s ready.

To enable **Account Rotation**, include this parameter when launching a workflow via API:

```json
{
  "account": [], // Provide the account ID(s) for rotation or leave it empty.
  "accounts_rotation_enabled": true
}
```

### **Refresh & Resume Paused Jobs**

<Info>
  Workflows may pause due to integration issues, such as a **broken cookie**.
  Here are several ways to address the issue.
</Info>

1. **Resume all paused jobs at once** while updating the user’s cookies:

   Use the **POST Add or Update an Integration Account** endpoint and set `resume_paused_jobs` to `true`:

   ```bash
   POST https://api.captaindata.co/v3/integrations/:integration_uid/accounts
   ```

   **Request payload example:**

   ```json
   {
     "account": {
       "uid": "Pass this UID to update an account only",
       "name": "Your account",
       "cookies": {
         "li_at": "YOUR_SESSION_COOKIE"
       },
       "user_uid": "67890-wxyz"
     },
     "resume_paused_jobs": true
   }
   ```

2. **To retry Specific Runs only:**
   Update the user account cookies and use the [**POST Retry a Run**](/v3/api-reference/runs/retry-job) endpoint:

   ```bash
   POST https://api.captaindata.co/v3/jobs/:job_uid/retry
   ```

   **Example payload:**

   ```json
   {
     "job_name": "Get Yann Lecun Linkedin Profile",
     "steps": [
       {
         "accounts": ["xxxxxx-63da-47f8-9a3c-53f2581d0ccb"],
         "accounts_rotation_enabled": false,
         "parameters": {},
         "output_column": null,
         "step_uid": "xxxxxx-xxxxx-451f-ac94-2b41972ec6a7"
       }
     ],
     "inputs": [
       {
         "linkedin_profile_url": "https://www.linkedin.com/in/yann-lecun/"
       }
     ]
   }
   ```

3. **For Shared Accounts:**
   Share this link with the account owner to refresh the cookie manually: `https://app.captaindata.co/integrations/linkedin/accounts/{user_id}`.

   This avoids waiting for Captain Data’s (or your own) Chrome extension to update it (updates occur every 2 hours).

   And then, use the [**POST Retry a Run**](/v3/api-reference/runs/retry-job) endpoint.

   For more information, see the related article: [Add & Managing Users](/v3/users-accounts/add-manage-users).

### Should I retry stopped Runs (Jobs) or not?

1. **Canceling Jobs:**

   You realize you did a mistake or the job is stuck for too long, you can cancel it using the [**POST Cancel a Run**](/v3/api-reference/runs/cancel-job) endpoint. This allows you to quickly stop any ongoing processes that are no longer needed.

2. **Restarting Stopped Jobs:**

   After addressing the issue, restart the job using the [POST Retry a Run](/v3/api-reference/runs/retry-job) endpoint. Ensure all necessary updates, such as fixing inputs or updating account credentials, are completed before retrying.

### **Managing Shutdown Job**

<Warning>
  **Polling for Shutdown Jobs:** Stop polling as soon as a job enters the
  **Shutdown** status; there’s no need to continue.
</Warning>

If you believe the inputs should work or need assistance, please **contact us** with all relevant details.

* **Single input:** You should receive a straightforward and clear error message for the shutdown status when running a single input. This is typically caused by an invalid cookie, so retrying is unnecessary.
* **By batch (multiple inputs):** If the API return the error **`All inputs failed. Please correct them before retrying your job.`**, it typically means the provided inputs are invalid.
  **In this case, check Inputs -** To gain more details regarding this error by inputs, use the [**Get a Run's Inputs**](/v3/api-reference/inputs/get-job-inputs):
  ```bash
  curl --request GET \
    --url https://api.captaindata.co/v3/jobs/{job_uid}/inputs \
    --header 'Authorization: <api-key>' \
    --header 'x-project-id: <project-id>'
  ```

By understanding and using retries effectively, you can overcome interruptions and keep your workflows on track.

### **Common Errors & How-to Retry**

<Info>
  Here's a list of the most common errors you could come across; classified by
  API.
</Info>

<AccordionGroup>
  <Accordion title="Users API">
    ### Create a User

    <Note>Attempted to create a user that is already in the database.</Note>

    * **Endpoint:** `POST` [Create or Update a User](/v3/api-reference/users/create-update-user)
    * **Error:** User already exists.
    * **Advice:** Perform a [GET "List all Users"](/v3/api-reference/users/list-users) API call and search by full name or email to verify if the user exists.
    * **Retry:** No — Use the GET API instead mentioned above to query the user(s).
  </Accordion>

  <Accordion title="Integration Accounts API">
    ### Add Integration Account

    <Note>The provided LinkedIn cookie is invalid or expired.</Note>

    * **Endpoint:** `POST Add or Update an Integration Account`
    * **Error:** Invalid or expired cookie.
    * **Advice:** Update the LinkedIn account’s cookie and retry the API call. Ensure the LinkedIn account is logged in and the cookie is valid.
    * **Retry:** No — A new API call is required with a valid cookie.

    ### Update Integration Account

    <Note>The request body did not include the "cookies" field.</Note>

    * **Endpoint:** `POST Add or Update an Integration Account`
    * **Error:** Missing cookies field.
    * **Advice:** Include a valid cookie in the request payload and retry.
    * **Retry:** No — The request must include valid cookies.

    ### Sync an Existing LinkedIn Account

    <Note>The account is already linked to another user.</Note>

    * **Endpoint:** `POST Add or Update Integration Account`
    * **Error:** Account already linked to another user.
    * **Advice:** Use the correct account or update the existing mapping with valid credentials.
    * **Retry:** No — Update should be done using the same account.

    ### Create LinkedIn Account Without `user_uid`

    <Note>An account can be created without associating it with a user upfront.</Note>

    * **Endpoint:** `POST Add or Update Integration Account`
    * **Error:** No error.
    * **Advice:** None.
    * **Retry:** No — No retries are needed as the operation is successful.

    ### Update Only Account Name

    <Note>User attempts to update the "name" field without providing cookies.</Note>

    * **Endpoint:** `POST Add or Update Integration Account`
    * **Error:** Missing cookies.
    * **Advice:** Include the cookies in the API request body and retry.
    * **Retry:** No — A new API call is required with valid cookies.
  </Accordion>

  <Accordion title="Jobs and Workflows API">
    ### Launch Workflow

    <Note>Invalid input data.</Note>

    * **Endpoint:** `POST Launch a Workflow`
    * **Error:** For example, "*The LinkedIn profile data provided is incorrect or does not exist.*"
    * **Advice:** Verify the input data and ensure the LinkedIn profile is valid.
    * **Retry:** No — Polling, if any, should stop immediately.

    ### Job Stuck with Account Rotation Enabled

    <Note>Workflow fails due to account disconnection.</Note>

    * **Endpoint:** `POST Launch Workflow` with parameter `account_rotation=true`
    * **Error:** The job was interrupted because the account was disconnected during execution.
    * **Advice:** Verify the account is valid and retry the job with account rotation enabled.
    * **Retry:** Yes — Retry with account rotation enabled.

    ### Job Stuck with Account Rotation Disabled

    <Note>Workflow fails due to account disconnection.</Note>

    * **Endpoint:** `POST Launch Workflow` with parameter `account_rotation=false`
    * **Error:** Invalid account.
    * **Advice:** Verify the account credentials and retry the job with valid cookies or account ID.
    * **Retry:** Yes — Retry after correcting the account credentials.
  </Accordion>

  <Accordion title="LinkedIn Automation Specific Errors">
    ### Connect LinkedIn Profile

    <Note>StatusCodeError: 400 - `{"code":"CANT_RESEND_YET"}`.</Note>

    * **Endpoint:** `POST Launch a Workflow`
    * **Description:** LinkedIn enforces a 3-week delay before you can resend a connection request to the same user after removing a pending request.
    * **Advice:** Wait for 3 weeks (21 days) before retrying the connection request.
    * **Retry:** No — Wait for the LinkedIn-imposed delay.

    ### Connect LinkedIn Profile (Rescheduled Job)

    <Note>No error, but the job is being rescheduled.</Note>

    * **Endpoint:** `POST Launch Workflow`
    * **Description:** If the profile hasn't reached its daily limit but the job keeps rescheduling, it likely means the profile has sent manual invites and reached its daily limit.
    * **Advice:** Wait until the daily limit resets before retrying.
    * **Retry:** No.

    ### Extract LinkedIn People Profile

    <Note>No results for this profile.</Note>

    * **Endpoint:** `POST Launch Workflow`
    * **Error:** The LinkedIn profile URL provided is inaccessible or invalid (e.g., 404 error).
    * **Advice:** Check the LinkedIn profile URL manually to ensure it is valid and accessible.
    * **Retry:** No — Correct the input data before retrying.

    ### Invalid LinkedIn Account

    <Note>No valid account provided for LinkedIn job execution.</Note>

    * **Endpoint:** `POST Launch Workflow`
    * **Error:** "There was no valid account given for LinkedIn - can't launch the job."
    * **Advice:** Verify the request body to ensure the account ID provided is valid (e.g., correct cookies or account ID).
    * **Retry:** Yes — Retry after including a valid account.
  </Accordion>
</AccordionGroup>