Errors

Problem details, stable codes, and what to do about each.

Errors are RFC 9457 problem details (application/problem+json) with a stable code and, for validation problems, an errors list with a path and a message each.

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "code": "invalid_state",
  "detail": "Required inputs could not be established from the supplied data. Nothing was guessed or executed.",
  "errors": [
    { "path": "state.damaged", "message": "required input could not be established from the supplied data; supply it explicitly" }
  ]
}

Status	Code	Meaning	What to do
400	`invalid_request`	The body is malformed; `errors` lists each problem with its path.	Fix the request.
401	`unauthorized`	Missing, invalid, expired or revoked API key.	Check the key; rotate it in the console.
402	`insufficient_balance`	Available credits cannot cover the request reservation.	Check Balance in the console; contact the preview team for credits.
400	`invalid_state`	A required fact is absent, unsupported or below its threshold. Nothing was executed. `errors[].path` names each missing input, as `state.<input>`.	Supply the fact or route for review. Use `blank` only if the written policy permits absence and the rules handle it.
422	`invalid_model`	A hand-written definition failed validation; `errors` lists every problem.	Check it through System Two with `content` and `output`, without a prompt or files.
422	`generation_failed`	The generator could not produce a valid model after its repair attempts.	Rephrase the prompt or questions; try `mode: thinking`.
422	`evaluation_failed`	The model could not be evaluated on these inputs.	Read `detail`; check the inputs against the schema.
503	`generation_unavailable`	No model provider is configured for a request that needs one.	Send a complete model definition with matching JSON inputs; contact support if generation is needed.
503	`reader_unavailable`	The state needs reading but no reader is configured.	Send a JSON state that matches the schema.
504	`generation_timeout`	Generation exceeded the request timeout.	Retry with backoff; simplify the request if the problem repeats.
500	`internal_error`	Something went wrong on our side.	Retry with backoff; report the receipt or request id.

Rate limits

If you receive 429, respect Retry-After when present and use exponential backoff.

Manual validation returns a stage report with valid: false for an invalid definition. Inspect that report even when the HTTP status is 200. An invalid model supplied for execution can return 422.

Aityx reserves credits before billable work, settles the completed charge, and releases unused reservations or failed work. Read the returned billing object for the charge and remaining balance.