Guides
Troubleshooting.
Use the HTTP status and response detail to decide what to fix or retry.
Common responses
| Status | Meaning | Next step |
|---|---|---|
| 400 / 422 | Invalid arguments or state | Check parameter names, enum values, and types against the tool schema. Run a simulation before reading results; clone a completed simulation before editing. |
| 401 | Missing or invalid key | Check the X-API-Key header and the deployment URL. |
| 403 | Permission denied | Check key scopes and workspace ownership. Workspace administration may require an operator key. |
| 404 / 410 | Resource unavailable | Check the simulation and workspace IDs. Expired, deleted, or evicted data must be recreated. |
| 409 | Conflicting operation | A simulation may already be running. Resolve its state before submitting another operation. |
| 429 | Limit reached | Read the response detail: a run budget is different from a temporary concurrency limit. Honor Retry-After if provided; do not retry in a tight loop. |
| 503 | Service unavailable | The service may be at capacity or have no healthy backend. Retry later if the response indicates a temporary condition. |
The exact status and detail can vary by deployment and routing layer. Keep the response body when diagnosing a failure.
A run timed out
A client timeout does not prove the server stopped the simulation. Check its state using list_simulations in the same workspace before retrying. Avoid blindly resubmitting creation or execution calls. Increase the read timeout for longer runs when appropriate.
A KPI is missing
Check get_available_results and the aggregate response’s skipped field. Availability depends on the scenario and link direction. Missing results are not zero-valued measurements.
Cleanup failed
Keep the simulation ID and retry delete_simulation after resolving the error. Save results locally before cleanup. Delete only simulations or workspaces owned by your workflow.