Documentation Index
Fetch the complete documentation index at: https://docs.lobstr.io/llms.txt
Use this file to discover all available pages before exploring further.
The lobstr.io API uses standard HTTP status codes. All error responses include a detail field with a human-readable message.
{
"detail": "A required parameter squid is missing from the route."
}
HTTP status codes
| Code | Meaning |
|---|
200 | Success |
400 | Bad request — invalid parameters or business logic violation |
401 | Unauthorized — missing or invalid API key |
403 | Forbidden — authenticated but not permitted |
404 | Not found — resource does not exist |
429 | Too many requests — rate limit exceeded |
500 | Server error — something went wrong on our end |
Authentication errors (401)
| Error | Description |
|---|
NotAuthenticated | No API key provided or the key is invalid |
TokenExpired | The authentication token has expired |
Authorization header is formatted exactly as Token YOUR_API_KEY.
Validation errors (400)
These occur when required parameters are missing or have the wrong format.
| Error | Description |
|---|
ParamsNeeded | A required parameter is missing (e.g., squid, tasks) |
MultipleParamsNeeded | Multiple required parameters are missing |
ParamsInvalid | A parameter value is invalid |
InvalidParamType | A parameter has the wrong type (e.g., string where integer expected) |
InvalidParameterValue | A parameter value is out of the allowed range |
BadEncoding | File encoding could not be recognized (upload endpoints) |
InvalidParam | General invalid parameter error |
Resource not found errors (404)
| Error | Description |
|---|
SquidDoesNotExistException | The specified squid does not exist or does not belong to you |
RunDoesNotExist | The specified run was not found |
TaskDoesNotExist | The specified task was not found |
TasksNotFound | No tasks found matching the criteria |
ModuleNotFound | The specified crawler does not exist |
FunctionNotFound | The specified crawler function does not exist |
AccountDoesNotExist | The specified account was not found |
AccountTypeDoesNotExist | The specified account type does not exist |
Business logic errors (400)
These occur when the request is valid but the operation can’t proceed due to account state.
| Error | Description |
|---|
NotEnoughBalance | Insufficient credits to start the run |
NoActiveSubscription | Account has no active subscription |
UsageLimitExceeded | Plan usage limit has been reached |
SlotsLimitExceeded | Maximum concurrency slots in use |
ConcurrencyLimitExceeded | Requested concurrency exceeds plan limit |
NoTasksPresent | Squid has no active tasks to run |
SquidNotReady | Squid is not in a state that allows running |
DuplicateSquid | A squid with the same name already exists |
PremiumModule | This crawler requires a paid plan |
ModuleUnavailable | The crawler is temporarily unavailable |
ModuleRestricted | Access to this crawler is restricted |
RunInProgress | A run is already in progress for this squid |
TaskNotValidError | Task parameters do not match the crawler’s requirements |
FileSizeLimitExceeded | Uploaded file exceeds the size limit |
Run stop reasons
When a run ends, the response includes a done_reason field (slug) and done_reason_desc (human-readable message) explaining why it stopped. These are not HTTP errors — they appear in the run object returned by Get Run Details.
Account errors
These indicate a problem with the account attached to the squid. Re-sync or replace the account, then resume the run.
done_reason | Description |
|---|
no_accounts | No accounts are linked to this squid — the run closes permanently. Fix: attach an account. |
no_account_available | Accounts are linked but all are currently in use by other runs — the run pauses and resumes automatically once one is free. |
account_blocked | The account has been blocked by the platform |
account_too_many_requests | The platform rate-limited the account |
cookies_expired | Account cookies have expired — re-sync required |
wrong_credentials | Account credentials are incorrect |
logged_out | The account has been logged out |
checkpoint_reached | The account is blocked on a checkpoint |
challenge_required | The platform is asking for a challenge |
non_premium | A premium platform account is required |
sales_seat_required | A Sales Navigator seat is required for this account |
limit_exceeded | The account has reached its platform usage limit |
General stop reasons
done_reason | Description |
|---|
tasks_done | All tasks completed successfully |
no_credits_left | Account ran out of lobstr.io credits |
deactivated | Run was deactivated |
website_inaccessible | Target website is currently down |
premium_plan_needed | A premium plan is required to run this module |
module_under_maintenance | Module is temporarily under maintenance |
request_failed | A request failed — run paused for 6 hours |
export_failed | Results export failed |
last_invoice_not_paid | Last invoice is unpaid |
maintenance_fees_not_paid | Custom module maintenance fees are unpaid |
batch_wait | Current batch processed — waiting for timeout |
emails_verified | All emails have been verified |
Rate limiting (429)
Requests that exceed your plan’s rate limit return a 429 response. See Rate Limiting for limits and retry guidance.
{
"detail": "Request was throttled. Expected available in 2 seconds."
}
Server errors (500)
| Error | Description |
|---|
SomethingWentWrong | An unexpected server-side error occurred |
Error handling example
import requests
def api_request(method, url, **kwargs):
response = requests.request(method, url, **kwargs)
if response.status_code == 401:
raise Exception("Authentication failed — check your API key")
if response.status_code == 404:
detail = response.json().get("detail", "Resource not found")
raise Exception(f"Not found: {detail}")
if response.status_code == 400:
detail = response.json().get("detail", "Bad request")
raise Exception(f"Bad request: {detail}")
if response.status_code == 429:
raise Exception("Rate limit exceeded — slow down requests")
if response.status_code >= 500:
raise Exception("Server error — try again later")
response.raise_for_status()
return response.json()
