# Statuses and errors

Reference for turn states, run interpretation, and common API error classes.

## Turn status

| Status        | Meaning                                |
| ------------- | -------------------------------------- |
| `queued`      | Accepted and waiting                   |
| `in_progress` | Active execution                       |
| `completed`   | Work and required durability completed |
| `failed`      | Execution or durability failed         |
| `cancelled`   | Intentionally cancelled                |
| `incomplete`  | Stopped without a complete result      |

## Error shape

```json
{
  "error": {
    "message": "Missing scope run:write",
    "type": "permission_error",
    "param": null,
    "code": "permission_denied"
  }
}
```

## HTTP classes

| Status | Typical meaning                                |
| ------ | ---------------------------------------------- |
| `400`  | Invalid request or model                       |
| `401`  | Missing, invalid or revoked API key            |
| `403`  | Missing scope or workspace permission          |
| `404`  | Resource not found in the authorized workspace |
| `409`  | Runtime readiness or lifecycle conflict        |
| `413`  | Payload exceeds a supported limit              |
| `429`  | Rate or quota limit                            |
| `500`  | Internal execution failure                     |

## Stable code examples

| Code                     | Meaning                                  |
| ------------------------ | ---------------------------------------- |
| `unauthorized`           | Authentication failed                    |
| `permission_denied`      | Scope or permission missing              |
| `not_found`              | Authorized resource not found            |
| `conflict`               | Request conflicts with runtime state     |
| `rate_limited`           | Request rate exceeded                    |
| `quota_exceeded`         | Account quota exceeded                   |
| `upstream_unavailable`   | Provider or dependency unavailable       |
| `run_failed_internal`    | Run failed inside the platform boundary  |
| `cannot_cancel_terminal` | Cancellation requested for terminal work |
| `stream_cursor_expired`  | Streaming cursor is no longer valid      |

## Interpreting stopped runs

Do not equate a cancelled run with a failed turn.

When all turns completed and the run stopped afterward during cleanup, Details
reports:

```text
turns completed, then the run stopped
```