Preflight and Errors

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

Use preflight before project runs

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; 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

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

MCP Tool Reference Outcome Rewards

⌘I

Getting Started

Managed Research

Stack

Research Factory

Prompt Optimization

Infrastructure

SDK Reference

Research API

Reference

Cookbooks

Preflight and Errors

Use preflight before project runs

Error contract

HTTP status codes customers see

Common blockers

Where to look next

​Use preflight before project runs

​Error contract

​HTTP status codes customers see

​Common blockers

​Where to look next

Use preflight before project runs

Error contract

HTTP status codes customers see

Common blockers

Where to look next