Handle errors and limits
Respond to Mantic API error status codes, retry safely and honour polling and rate-limit headers.
Read the error body
Error responses are JSON with a detail field. For most errors detail is a message:
{
"detail": "Question with ID 1234 not found"
}For validation errors (422), detail is usually a list with one entry per problem, giving its location (loc), a message (msg) and an error type. Don't parse the message text; it can change.
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | The request is well formed but the endpoint can't serve it, for example search combined with after on GET /dashboards/{dashboard_id}/questions, or a CDF the forecast run can't provide. | Fix the request. Don't retry it unchanged. |
401 | The access token is missing, invalid or expired. | Get a new access token and retry once. |
403 | Your credentials can't make this change, for example adding a forecast to a dashboard they can't edit (beta). | Ask your Mantic contact for access. |
404 | The resource doesn't exist or isn't available to your credentials. GET /questions/{question_id} also returns 404 until the forecast has a completed run. | Check the ID. For a newly created forecast, try again later. |
409 | The request conflicts with the current state, for example a draft that has already been used to create a forecast (beta). | Don't retry. Read the current state instead. |
422 | Validation failed: a parameter or body field is missing or invalid, a JSON-encoded parameter (filter, sort, after, question_ids) can't be parsed, or search is combined with after on GET /questions or GET /dashboards. | Fix the request using detail. |
429 | You've used your forecast-creation allowance (beta POST /questions). | Wait for the number of seconds in Retry-After. |
503 | A dependent service, such as authentication or search, is temporarily unavailable. | Retry after a short delay with backoff. |
Redacted runs are not errors
A run with "type": "redacted" is a successful response without values: show_forecasts was false, or omitted and your organisation's default is off. Send show_forecasts=true; see Redacted and unknown.
Pace your requests
GET /questions and GET /questions/{question_id} return an ETag and X-Poll-Interval. When you poll, send the ETag value in If-None-Match; a 304 with no body means nothing has changed. Wait the number of seconds in X-Poll-Interval between polls.