Skip to content
Core Concepts

Errors

HTTP status codes and error types returned by the lobstr.io API

The v1 API, for batchesSquids, tasks and runs: many calls on a schedule, delivered where you work. For one call that answers in seconds, use the API v2.

The lobstr.io API uses standard HTTP status codes. All error responses share one envelope: an errors object with message (human-readable), type (the error code from the tables below), and code (the HTTP status, repeated).

{
  "errors": {
    "message": "A required parameter squid is missing from the route.",
    "type": "ParamsNeeded",
    "code": 400
  }
}

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 Your runs in progress already use your plan's slots: launching, resuming, resurrecting or retrying a run, or raising a running squid's concurrency, would go past them. Nothing is queued: launch again when a run finishes, or stop one. Also returned when a squid's concurrency is set above the plan's slots
SquidsLimitExceeded Your plan holds up to 100 squids per slot (Free 100, Starter 200, Pro 1,000, Team 5,000): delete squids you no longer need, or upgrade
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
DataRetentionPeriodExceeded The run is past its expires_at: your plan no longer keeps its results (Free 7 days, paid plans 45, 1,000,000 credits a month or more 90). The message gives the date

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.

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 blocked requests (403/429) or is down (5xx) — run paused 10 minutes, then resumes
temporary_issue A proxy, network or browser failure on lobstr.io's side — run paused 10 minutes, then resumes
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
waiting_sending_slot Leboncoin Auto Message Sender: waiting for a free sending slot — run paused about 10 minutes, then resumes
message_preparation_stopped Leboncoin Auto Message Sender: the message could not be prepared — run stopped, the run log gives the exact reason
emails_verified All emails have been verified

Rate limiting (429)

Requests that exceed your plan's rate limit return a 429 response, in the same errors envelope as every other error:

{
  "errors": {
    "message": "Request was throttled. Expected available in 2 seconds.",
    "type": "...",
    "code": 429
  }
}

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

Python
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:
        message = response.json().get("errors", {}).get("message", "Resource not found")
        raise Exception(f"Not found: {message}")

    if response.status_code == 400:
        message = response.json().get("errors", {}).get("message", "Bad request")
        raise Exception(f"Bad request: {message}")

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