Skip to main content
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

StatusMeaningWhat to do
402Insufficient credits or spend headroom (smr_insufficient_credits)Check Usage and Budgets; add credits, reduce scope, or upgrade plan
429Rate, capacity, or concurrent-run limit (smr_limit_exceeded)Retry later, reduce parallel launches, inspect limit progress tools
409Funding-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

BlockerMeaning
Unsupported harness/model pairThe selected agent_model is not available for the selected agent_harness.
Unsupported reasoning effortThe requested agent_model_params.reasoning_effort is not listed for that model.
Missing authSYNTH_API_KEY or workspace credentials are missing or invalid.
Budget exceededRun or monthly budget caps prevent launch or stop runtime.
Project setup incompleteRepo, setup, onboarding, or runtime requirements are not ready.
Provider unavailableProvider binding is missing, disabled, or lacks required capability.
Approval requiredThe run is blocked until an operator action is resolved.

​
Where to look next