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?
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)?
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:
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?
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?
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?
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?
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?
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?
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?
How to handle authentication errors?
For authentication errors:
LK_BAD_COOKIE: Update your LinkedIn account cookies in the platform401: Check your API credentials and account permissions403: Verify your account has the necessary permissions for the operation
Related Article: LinkedIn Accounts