<!-- https://predictabl.tech/docs/errors-and-limits/ -->
# Errors and limits

## Errors

Every error from the Python library is a `predictabl.PredictablError` with
`.code` (the API's code, when it sent one), `.status` (the HTTP status) and
`.message`, written to say what to do next.

```python
import predictabl as pb

try:
    model = data.predict("Which customers will churn?")
except pb.LimitReached as e:
    print(e.message)        # how to continue
except pb.PredictablError as e:
    print(e.code, e.message)
```

| Exception | HTTP | Means | Do |
|---|---|---|---|
| `AuthenticationError` | 401 | The key is missing, wrong or revoked | Check `PREDICTABL_API_KEY`; create a new token |
| `LimitReached` | 402 | An allowance of your plan is used up | The message says what is left and how to continue. Retrying will not help |
| `PermissionDenied` | 403 | The token's access does not allow this | Use a **Full access** token to upload or train |
| `NotFound` | 404 | No such dataset, question or model on this account | Check the id. Other accounts' objects also answer 404 |
| `InvalidRequest` | 4xx | The request was refused; the message says why | Fix the request |
| `BuildFailed` | — | Reading the data, planning or training failed | Read `.message` and `.suggestions` |
| `ApiError` | 5xx | Something failed on the server, or it could not be reached | Retry later. Reads are retried for you |

### Codes you may see

| Code | Where | Meaning |
|---|---|---|
| `CREDITS_EXHAUSTED` | Planning or changing a plan | Not enough credits left for this |
| `MODEL_LIMIT` | Planning or training a new question | Your plan's number of models is reached; delete one to make room |
| `PREDICTIONS_LIMIT` | Scoring | This request needs more predictions than are left this month; nothing was scored or counted |
| `SCHEDULES_PAID` | Creating or resuming a schedule | Schedules are on paid plans |
| `FILE_TOO_LARGE` | Uploading | A file is larger than your plan allows |
| `MISSING_REQUIRED_FIELDS` | Scoring records | A record leaves out a field the model needs; `details.missing` lists them |
| `LLM_DAILY_LIMIT` | Any step that uses AI | Today's AI calls on Predictabl's key are used; resets at 00:00 UTC |
| `PREDICT_UNAVAILABLE` | `model.predict()` | This model cannot score that way; for a flat model, send `rows=` |
| `RUN_NOT_READY` | Scoring | The model has not finished training |
| `NOT_FOUND` | Anywhere | The id does not exist on this account |
| `SPEC_CONFLICT` | Changing a plan | Someone changed the plan at the same time; read it again |

A training run that fails ends with `state: FAILED`, an `error_code`, an
`error_message` and `suggestions`, which `BuildFailed` carries.

## Limits

### Your plan

Your plan's allowances, and how much of each is left, are in **Settings → API &
MCP**, or from code:

```python
acct = pb.account()
acct["credits"]                     # balance, and what a model costs
acct["predictions_this_month"], acct["predictions_monthly_limit"]
acct["models_kept"], acct["models_limit"]
```

- **Credits** pay for the AI work on Predictabl's key: turning a question into
  a plan, and changing a plan. Training, retraining and predictions never use
  credits. A plan or model that fails to build is refunded automatically.
- **With your own OpenAI or Anthropic key** (**Settings → AI provider**),
  building uses no credits: you pay your provider directly. Your plan's other
  allowances still apply.
- **Predictions** are counted per prediction returned, across all your models. The
  Prediction explorer in the web app is not counted. A request is all or
  nothing: if it needs more than you have left, nothing is scored or counted,
  and the message says how many it needed.
- **A limit of `None`** means your plan has none for that allowance.

A daily cap on AI calls on Predictabl's key stops a runaway script; it resets
at 00:00 UTC.

### Requests

| | Limit |
|---|---|
| Records per `predict-records` request | 1,000 (the Python library batches for you) |
| Predictions per `predict` request | 2,000 |
| Upload size | 200 MB per request |
| Request duration | 15 minutes; long work runs in the background and is polled |
