# 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).

```json
{
  "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](https://staging.docs.lobstr.io/docs/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:

```json
{
  "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

<CodeGroup>
```python 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()
```
</CodeGroup>
