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.
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:
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
Nonemeans 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 |