Status codes
HTTP status codes and resource statuses used by the API.
HTTP status codes
Request succeeded. Response body contains the requested data.
Resource created successfully. Response body contains the new resource.
Request succeeded with no response body (e.g., DELETE operations).
Invalid request body or parameters. Check the error message for details.
The requested resource does not exist.
Request body failed validation. Response contains field-level errors.
Unexpected server error. Please report if persistent.
Simulation status
Simulations and reports progress through these statuses:
Queued and waiting for a worker to pick up
Currently being processed by a worker
Successfully finished processing
An error occurred during processing
Error response format
Error responses follow a consistent format:
{
"detail": "Error message describing what went wrong"
}Validation errors (422) include field-level details:
{
"detail": [
{
"loc": ["body", "dataset_id"],
"msg": "field required",
"type": "value_error.missing"
}
]
}Polling strategy
For async operations like simulations and reports:
- Submit the request (POST) and receive the resource with pending status
- Poll the GET endpoint every 2-5 seconds
- Check the status field in the response
- Stop polling when status is completed or failed
- If failed, check the error_message field for details
Tip: Use exponential backoff for production systems to avoid overwhelming the API during high load.