Errors

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

Make sure your 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

If you encounter repeated 500 errors, contact support with the request details.

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()

Overview

Getting Started

Core Concepts

User

Crawler

Squid

Delivery

Account

Task

Run

Result

HTTP status codes

Authentication errors (401)

Validation errors (400)

Resource not found errors (404)

Business logic errors (400)

Run stop reasons

Account errors

General stop reasons

Rate limiting (429)

Server errors (500)

Error handling example

​HTTP status codes

​Authentication errors (401)

​Validation errors (400)

​Resource not found errors (404)

​Business logic errors (400)

​Run stop reasons

​Account errors

​General stop reasons

​Rate limiting (429)

​Server errors (500)

​Error handling example

HTTP status codes

Authentication errors (401)

Validation errors (400)

Resource not found errors (404)

Business logic errors (400)

Run stop reasons

Account errors

General stop reasons

Rate limiting (429)

Server errors (500)

Error handling example