---
title: Errors
description: Problem details, stable codes, and what to do about each.
icon: triangle-alert
---

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.

```json
{
  "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. |

| 429 | `generation_busy` | The configured generation limit is occupied. | Retry with backoff; avoid parallel retries. |

## 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.