Errors
HTTP status codes and error types returned by the lobstr.io API
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
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()