API reference

Errors and limits

Errors are rare and always explicit: a status code, a stable error code, and a message that says what to fix.

Error format#

Every error response has the same shape:

422 Unprocessable Entity

{
  "error": {
    "code": "invalid_request",
    "message": "`candidates` must be a non-empty array."
  }
}

Branch on code, which is stable. The message is written for humans and may change.

Status codes#

Status	Code	Meaning	What to do
`400`	`invalid_json`	The body isn't valid JSON.	Fix the serialization.
`400`	`invalid_body`	The body isn't a JSON object.	Send an object.
`401`	`invalid_api_key`	The key is missing, wrong or revoked.	Check `CONTEXTWAISE_API_KEY`.
`422`	`invalid_request`	A field is missing or out of range.	The message names the field.
`429`	`rate_limited`	Your plan's requests per minute are used.	Send your original context; retry after `Retry-After` seconds.
`429`	`quota_exceeded`	Free plan only: the one-time 1M free tokens are used.	Send your original context; upgrade to Pro or Scale in Billing.
`500`	`internal_error`	Something went wrong on our side.	Send your original context; retry later.
`503`	`scoring_unavailable`	Contextwaise is having trouble judging relevance right now.	Send your original context; retry after `Retry-After` seconds.

Note

Contextwaise never cuts context on a guess: when relevance can't be judged, you get a 503 instead of a weaker result (see When scoring is unavailable).

Handling errors#

In production, every error has the same answer: send your original context and carry on. Contextwaise optimizes a request; it should never block one. The fail-open helper does exactly this, including for timeouts and network errors.

400, 401 and 422 point to a bug or a configuration problem: log them, so they get fixed instead of silently costing you savings.

Request limits#

Limit	Value
`query` length	8,000 characters
Candidates per request	500
Candidate `text` length	60,000 characters
Candidate `id` length	80 characters (longer ids are cut)
`budget`	200 to 200,000 tokens (values outside are clamped)
`models` for routing	2 to 10, each in the catalog or priced in Settings → Models
`conversation` id	1 to 128 characters: letters, digits, `_ - . :`

Plan limits#

Optimize requests and agent SDK scoring calls share one per-minute limit per organization, across all its keys: 60 on Free, 1,000 on Pro, 3,000 on Scale. Free stops once its 1M free context tokens are used: they are a one-time allowance to try Contextwaise, and don't renew. Pro and Scale keep running past their monthly allowance, with extra tokens billed. Both return 429; the rate limit adds Retry-After. The agent SDK handles it for you: it passes cleaned outputs whole and retries 30 seconds later.

Apart from budget, requests beyond these limits return 422 with the field and limit in the message. For larger inputs, split them across candidates: Contextwaise decides item by item, so finer items also give finer cuts.