> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesynth.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Preflight and Errors

> Diagnose launch blockers, preflight denials, budget stops, and unsupported configuration.

Preflight checks whether a run can launch before Synth spends runtime.

## Use preflight before project runs

```python theme={null}
from synth_ai import SynthClient

research = SynthClient().research

preflight = research.runs.launch_preflight(
    project_id="proj_…",
    host_kind="daytona",
    work_mode="directed_effort",
    providers=[{"provider": "openrouter"}],
    runbook="lite",
)

if not preflight.get("clear_to_trigger"):
    raise RuntimeError(preflight.get("resolution_reason") or "Run is not ready to start")
```

## Error contract

Launch denials are errors:

* MCP returns tool errors with structured payloads (`error`, `http_status`, `detail`).
* Python raises typed exceptions (`ResearchInsufficientCreditsError`, limit errors, and related SMR errors).
* Direct `/smr` REST is not the public external integration path.

Do not build integrations that expect success payloads with embedded error fields.

## HTTP status codes customers see

| Status  | Meaning                                                                        | What to do                                                                                      |
| ------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| **402** | Insufficient credits or spend headroom (`smr_insufficient_credits`)            | Check [Usage and Budgets](/managed-research/usage); add credits, reduce scope, or upgrade plan  |
| **429** | Rate, capacity, or concurrent-run limit (`smr_limit_exceeded`)                 | Retry later, reduce parallel launches, inspect limit progress tools                             |
| **409** | Funding-lane or routing invariant (for example Free tier on a disallowed pool) | Change harness/model/provider per entitlement; see [Beta Access](/managed-research/beta-access) |

Console and SDK copy should name the **blocking resource** and the **next action**, not a generic failure string.

## Common blockers

| Blocker                        | Meaning                                                                           |
| ------------------------------ | --------------------------------------------------------------------------------- |
| Unsupported harness/model pair | The selected `agent_model` is not available for the selected `agent_harness`.     |
| Unsupported reasoning effort   | The requested `agent_model_params.reasoning_effort` is not listed for that model. |
| Missing auth                   | `SYNTH_API_KEY` or workspace credentials are missing or invalid.                  |
| Budget exceeded                | Run or monthly budget caps prevent launch or stop runtime.                        |
| Project setup incomplete       | Repo, setup, onboarding, or runtime requirements are not ready.                   |
| Provider unavailable           | Provider binding is missing, disabled, or lacks required capability.              |
| Approval required              | The run is blocked until an operator action is resolved.                          |

## Where to look next

* [Models and Harnesses](/managed-research/models-and-harnesses)
* [Providers and Credentials](/managed-research/providers-and-credentials)
* [Usage and Budgets](/managed-research/usage)
* [Runs and Evidence](/managed-research/runs-and-evidence)