FAQ & Troubleshooting

Find answers to common questions and troubleshooting tips for using the Captain Data API, including error handling, best practices, and debugging guidance.

There are two ways to use Captain Data: through our API or the Platform UI. If you’re a platform user, head over to the Legacy Platform Documentation section of the documentation.

Manage Workflows & Jobs

Can I create workflows via the API?

Currently, workflows cannot be created directly via the API; they must be set up through the platform interface. If needed, you can duplicate workflows (and folders) to support tasks like separating work in a staging environment from deploying and switching to production.

Related Article: Actions & Flows Library

How to retry a Run (Job)?

To retry a job using the Captain Data API, you can make a POST request to the following endpoint:

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

Replace :job_uid with the unique identifier of the job you want to retry.

For more detailed control over how to retry the job, you can also use the Launch Workflow endpoint, as the payload is exactly the same for both.

It will retry the job by creating another sub-job in the step. (or each steps if multiple ones)

You can find more information in the API Reference Retry a Run.

Related Article: Retry a Run

How to Manage Webhooks?

Webhooks allow you to trigger specific events related to job statuses, such as:

• A job succeeded
• A job failed
• A job was created

This is an excellent practice if you want to monitor job statuses in real-time and stop polling for job results. For more details, check out this guide: Polling Data

Related Article: Add & Manage Webhooks

How to format a JSON payload configuration to Launch a Workflow?

Use the API Playground to help generate a cURL or the correct Body to Schedule for scheduling workflows. For each step(s) you’ll have to adjust inputs, parameters, accounts for each specific run.

Related Article: Quickstart

How to delete a scheduled job?

A scheduled job is an execution of the workflow that it set to run in the future (next hour, month, year..) and repeated (never, everyday, week, etc.).

To delete a scheduled job, use the endpoint DEL - Remove Schedule. This will remove the schedule but keep the jobs that have already ran.

Related Article: Manage & Delete Scheduled Runs (Jobs)

When a User is deleted, are their repeat runs (jobs) also deleted?

No, the user’s repeat jobs are not deleted automatically.

Troubleshooting Errors

If you encounter an unusual error like 503 - Cannot undefined, don’t hesitate to reach out to us! This is an internal error on our end, and we’ll be happy to help resolve it.

Below is a comprehensive reference of common errors you may encounter when using the Captain Data API, organized by category with recommended actions.

HTTP Status Codes

HTTP Status Codes are standard response codes returned by web servers to indicate the outcome of an HTTP request. They help you understand whether your request was successful, encountered an error, or requires further action.

Status Code	Description	Action Required
200	OK - Request was successful	None - Operation completed successfully
201	Created - Resource was successfully created	None - Operation completed successfully
400	Bad Request - Request could not be understood or was missing required parameters	Review and correct your request parameters
401	Unauthorized - Authentication failed or user doesn’t have permissions	Check your authentication credentials and permissions
403	Forbidden - Access denied	Contact support if this error persists
404	Not Found - Resource was not found	Verify the resource exists or check your request URL
405	Method Not Allowed - Requested method is not supported for resource	Use the correct HTTP method for the endpoint
429	Too Many Requests - Rate limited	Wait before making additional requests
500	Internal Server Error - Server error from external website	Contact support - can be retried manually
502	Bad Gateway - Bad response from external website	Contact support - can be retried manually
503	Service Unavailable - External website service unavailable	Contact support - can be retried manually
504	Gateway Timeout - External website timeout	Contact support - can be retried manually

Authentication & Cookie Errors

Authentication & Cookie Errors occur when your credentials, tokens, or session cookies are missing, invalid, or expired. These errors prevent you from accessing protected resources or performing certain actions.

Error Code	Description	Action Required
LK_BAD_COOKIE	Update your LinkedIn integration’s account (your cookie is not valid)	Must update your account and retry the job
401	Authentication required	Can be an input issue or configuration problem - correct and retry

Access & Permission Errors

Access & Permission Errors indicate that your account or API key does not have the necessary rights to access a resource or perform an operation. This can be due to insufficient permissions or restricted content.

Error Code	Description	Action Required
LK_403	This page is not accessible	Nothing to do - the profile is not accessible
403	Access denied	Contact support - error not caught by Captain Data

Rate Limiting & Limits

Rate Limiting & Limits errors occur when you exceed the number of allowed requests or actions within a certain time frame. These safeguards help prevent abuse and ensure fair usage of the API.

Error Code	Description	Action Required
LIMIT_REACHED	{{timespan}} limit reached for {{service}}	Retry - occurs when service limits are reached
RATE_LIMITED	You have been rate limited, waiting before launching next request	Automatic retry - handled by Captain Data
429	You have been rate limited, waiting before launching next request	Automatic retry - handled by Captain Data

Network & Connection Errors

Network & Connection Errors happen when there are issues with connectivity, timeouts, or communication between your client and the server. These are often temporary and can be resolved by retrying the request.

Error Code	Description	Action Required
API_MAX_RETRY	Error while making API call: Max retries of {{max}} reached for this call with reason {{reason}}	Retry the operation
API_TIMEOUT_ERROR	Timeout of {{timeout}} ms exceeded	Retry the operation
ECONNRESET	Connection reset - retrying indefinitely…	Retry the operation
ETIMEDOUT	Timed out - retrying indefinitely…	Retry the operation
HPE_HEADER_OVERFLOW	HTTP Header too large ({{size}})	Retry the operation

Business Logic Errors

Business Logic Errors occur when the request is technically valid, but the data or parameters provided do not meet the requirements or rules of the application. These errors often indicate issues with your input, such as missing fields, invalid values, or logical conditions not being met.

Error Code	Description	Action Required
NO_RESULT	No results for {{input}}	Nothing to do - no data found for the given input
BAD_INPUT	Invalid input provided	Correct your input and retry
MISSING_PARAMETER	Missing required parameter {{parameter}}	Add the missing parameter and retry
UNDEFINED_FIELD	One or multiple of the necessary values are undefined: {{fields}}	Correct your input/parameter and retry
NOT_CONNECTED	You are not connected with {{handle}}	Nothing to do - connection doesn’t exist
BAD_PARAMETERS_NON_BLOCKER	Parameter {{parameter}} is invalid: {{explanation}}	Correct your parameter and retry

Generic Errors

Generic Errors are unexpected issues that do not fit into other categories. They may be caused by unforeseen conditions, unhandled exceptions, or errors not specifically caught by Captain Data. If you encounter these, it’s best to contact support.

Error Code	Description	Action Required
GENERIC_ERROR	Error while {{action}}: {{error}}	Contact support - error not caught by Captain Data
GENERIC_NON_BLOCKER_ERROR	Error while {{action}}: {{error}}	Contact support - error not caught by Captain Data

Error Handling Best Practices

When should I retry a job?

Retry jobs when you encounter:

• Network errors (ECONNRESET, ETIMEDOUT, API_TIMEOUT_ERROR)
• Rate limiting errors (RATE_LIMITED, 429)
• Limit reached errors (LIMIT_REACHED)
• Temporary server errors (500, 502, 503, 504)

Use the Retry a Run endpoint to retry failed jobs.

When should I contact support?

Contact support when you encounter:

• Generic errors (GENERIC_ERROR, GENERIC_NON_BLOCKER_ERROR)
• Unexpected 403 errors
• Server errors from external websites (500, 502, 503, 504)
• Any error that doesn’t match the patterns above

Include the job UID and error details when contacting support.

How to handle authentication errors?

For authentication errors:

• LK_BAD_COOKIE: Update your LinkedIn account cookies in the platform
• 401: Check your API credentials and account permissions
• 403: Verify your account has the necessary permissions for the operation

Related Article: LinkedIn Accounts