API reference
Errors, limits & billing
Errors#
Errors return JSON with an error (or detail) message that says what to fix.
{ "error": "Choice 'intent' criteria must map 2 to 256 options" }
400
bad request
The body is not valid JSON, or a field is missing, too long or of the wrong shape. Fix the request; retrying will not help.
401
unauthorized
Missing or invalid API key.
429
rate limited
Over your key's limits (below). Wait for
Retry-After seconds, then retry.502
upstream error
The model could not produce a valid answer. Rare; safe to retry once.
503
unavailable
The service is starting, waking from idle (
Retry-After: 90, about 1.5 to 2 minutes; see Status), or temporarily unavailable. Retry with backoff.Retries
Decisions are read-only, so retrying a 502 or 503 is always safe. Use exponential backoff starting at about one second, and a client timeout of at least 60 s so thought answers can finish.
Limits#
Rate
per key
20 requests per second with bursts of up to 40, and 32 requests in flight. Beyond that:
429 with Retry-After. Need more? Email us.Request body
size
Up to 12 MB, including an image.
image
count
One per request, as a data URL.
generate max_tokens
count
1 to 512 per request.
state
length
Up to 32,000 characters (objects and arrays are measured after JSON encoding).
instructions
length
Up to 4,000 characters per question.
choice options
count
2 to 256 per question; ids up to 128 characters, descriptions up to 2,000.
score levels
count
2 to 10 per question.
Question names
length
Up to 128 characters.
Billing#
You pay for what you send, counted once: $0.042 per million input tokens, output free. Nothing about how Wity reaches the answer is billed. See Pricing for examples.
usage.input_tokensis your request (state, instructions and criteria) counted once per question.usage.output_tokensis 0 for decisions; for generate it reports the text written, which is not billed.- Each question is billed with the state it reads, so several questions cost about the sum of asking each. Asking them in one request saves round trips, not tokens; keep the state to what the decisions need.
Privacy#
Request and response bodies are not logged. We keep only operational records: which key made a request, when, its status and how long it took.