Errors and limits

Errors

Errors always look like this, with a short, plain message:

json

{ "error": { "type": "invalid_request", "message": "Send `state`: text, a JSON object or an array." } }

Status	`error.type`	What to do
400	`invalid_request`	fix the request; the message says what's wrong
401	`authentication_error`	check the key and the `Authorization` header
402	`payment_required`	the free trial has ended and there's no active subscription, or the trial's 3 builds are used: subscribe in the console (Billing). The models you already have are yours to download
404	`not_found`	check the domain name, version or id
409	`conflict`	it already exists, or the domain isn't ready for that yet
413	`too_large`	split the upload
429	`rate_limited`	wait for `Retry-After` (1 second for the rate limit), then retry; a build limit says when it opens again
500	`server_error`	retry with backoff; tell us if it persists
503	`unavailable`	a feature that isn't switched on yet, or a short outage

The hosted endpoint allows 50 requests per second per key by default. Above that you get 429 with Retry-After: 1. Nothing is ever charged for it: pricing is flat, $20 a month per workspace, with unlimited decision models, decisions and retraining.

Build limits

A build is a new model, a new version from POST /v1/build, or a rule change. Each workspace can start:

	Builds
a day (UTC)	5
during the free trial, in all	3
a calendar month, with a subscription	30

Retraining a built model doesn't count as a build; it has a fair-use limit of 20 retrains a day. Past a limit you get 429 rate_limited (or 402 payment_required when the trial's builds are used up), with a message that says which limit was reached and when it opens again. Your models keep working, and you can still retrain them. GET /v1/account shows where you are in usage.builds, and the console shows it under Billing.

Free trial and subscription

Your 5-day free trial starts when your workspace trains its first model or makes its first decision, not when you sign up, and needs no card. After it, the subscription ($20 a month per workspace, flat) pays for improving your models: training, new options and actions, day-one questions switching to your own model, and the hosted endpoint. Without one, those answer 402 payment_required (and automatic switching waits); everything else keeps working: the console, reports and versions, uploads, set-up, reviewing examples and billing.

Your models are yours to keep. Every version you trained, during the trial or while subscribed, can be downloaded at any time, and a downloaded model keeps working offline. GET /v1/billing says where you are: trial.state (not_started, active or ended), trial_ends_at, and can_train, can_decide and can_download.

Need more throughput? Ask several questions in one request (they're answered together), or run the model yourself for any volume.

The open demo endpoint (/v1/demo/decide) allows 30 requests per minute per IP.

Retries

Retry 429, 500 and 503 with exponential backoff and jitter.
Don't retry 400, 401, 402, 404, 409 or 413 unchanged.
A retried /v1/decide is answered again and counted as another decision; with flat pricing that costs nothing.

Sizes

Choice questions take 1 to 255 options; Score questions 2 to 10 levels.
Uploads through the console go up to 20 MB; send bigger files straight to the API.
train with wait: true waits up to about 10 minutes; use wait: false and poll GET /v1/jobs/{job_id} for longer runs.