Get Started Free

Errors and limits

How the InduQT API reports errors, what each HTTP status means, the rate limits, and how to retry safely.

Error format

Errors use standard HTTP status codes and a JSON body with a human-readable error message and, where the client can act on it, a stable machine-readable code.

Error body
{
  "error": "name is required",
  "code": "invalid_request"
}
Error body fields
FieldTypeDescription
errorstringWhat went wrong, written for a developer. Show it in logs; do not parse it.
codestring, optionalA stable identifier for the kind of error. Branch on this (or on the status) rather than on the message.

Status codes

HTTP status codes
StatusMeaningWhat to do
400 Bad RequestThe body or a parameter is invalid: a missing required field, a wrong type, an unknown family, a bad time, a signal key with characters other than letters, digits, _ . -.Fix the request. The error message names the field.
401 UnauthorizedNo Authorization header, a malformed one, or a key that does not exist or was revoked.Check the header is Bearer iq_live_… and the key is still listed in Settings.
403 Forbidden (scope)The key is valid but lacks the scope this endpoint needs, or it is limited to another site.Use a key with the right scope, or create one. See Authentication.
403 Forbidden (plan)The plan does not include this: the machine allowance is used up, live connectors need Plant Monitor or Enterprise, or the AI diagnosis allowance is spent.Upgrade the plan, or delete unused machines.
404 Not FoundThe resource does not exist, or belongs to another account. The two are deliberately indistinguishable.Check the id and that the key is for the right account.
409 ConflictThe change clashes with existing data: a site name or externalId already in use, deleting a site that still has machines or connectors, stopping a recording that is not live.Read the current state, then change the request.
413 Payload Too LargeIngest bodies over 1 MB or 5,000 readings; import files over 20 MB or 500,000 rows.Split into smaller batches or files.
415 Unsupported Media TypeThe body is not JSON, or an import file is not CSV or XLSX.Send Content-Type: application/json; convert the file.
429 Too Many RequestsThe key went over its rate limit.Back off and retry; batch readings.
5xx Server ErrorSomething failed on our side or upstream (500, 502, 503, 504).Retry with backoff. If it persists, email support with the time and request.

Rate limits

  • Ingest: Rate limit: 600 requests a minute per key. Batch when sending more than a few readings a second.
  • Batch size: one ingest request takes up to 5,000 readings or 1 MB, whichever comes first.
  • Imports: up to 20 MB and 500,000 rows per file.

Over the limit, the API answers 429. If the response has a Retry-After header, wait that many seconds before retrying.

Retries

Retry 429 and 5xx responses and network errors, with exponential backoff and jitter (for example 1 s, 2 s, 4 s, 8 s, up to a minute). Do not retry other 4xx responses unchanged: they will fail the same way.

  • Ingest is idempotent. Readings for the same machine, signal and timestamp overwrite each other, so retries are safe. Gateways can resend a buffered batch after an outage without creating duplicates.
  • Creates are not. Retrying POST /v1/sites, /v1/machines, /v1/connectors or /v1/api-keys after a timeout can create a second resource, or answer 409 when the name must be unique. List first, then create only if it is missing.
  • Updates and deletes (PATCH, DELETE) are safe to repeat. A repeated delete may answer 404; treat that as done.
  • AI analysis counts against the plan on each successful call, so do not retry POST /v1/recordings/{recordingId}/analyze after it succeeded; read the result with GET /v1/recordings/{recordingId}.
Retry with backoff (bash)
for i in 1 2 3 4 5; do
  status=$(curl -s -o /tmp/induqt.json -w '%{http_code}' -X POST "https://api.induqt.ai/v1/ingest" \
    -H "Authorization: Bearer $INDUQT_API_KEY" -H "Content-Type: application/json" \
    -d '{"machine":"B-101","values":{"steam_pressure":112.4}}')
  case "$status" in
    2??) cat /tmp/induqt.json; break ;;
    429|5??) sleep $((2 ** i)) ;;
    *) cat /tmp/induqt.json; exit 1 ;;
  esac
done
Contacting support

Email support@induqt.ai with the time (UTC), method and path, status and error body. Never send the API key.