Errors

The Haltless API uses standard HTTP status codes and returns structured JSON error bodies.

Error response shape

Most errors return a single human-readable message:

{
  "detail": "Machine not found."
}

Some errors return a structured body with a machine-readable error_code:

{
  "error_code": "validation_error",
  "message": "Request validation failed.",
  "details": {
    "errors": [
      {
        "loc": ["body", "value"],
        "msg": "Sensor value must be a finite number (not NaN or Infinity).",
        "type": "value_error"
      }
    ]
  }
}

HTTP status codes

Success

Code	Meaning	When
200 OK	Success	Standard successful response
201 Created	Resource created	A request that creates a resource
204 No Content	Success, no body	Deletes, logout, and similar
207 Multi-Status	Partial success	Batch ingestion with mixed results

Client errors

Code	Meaning	Common causes
400 Bad Request	Invalid request	Missing fields, malformed JSON
401 Unauthorized	Authentication failed	Missing, expired, or revoked token
403 Forbidden	Not permitted	Your role cannot perform this operation
404 Not Found	Resource not found	Unknown ID, or a resource you cannot access
409 Conflict	Conflicting state	Duplicate identifier, already acknowledged
422 Unprocessable Entity	Validation error	The request body fails schema validation
429 Too Many Requests	Rate limited	See Rate Limiting

Server errors

Code	Meaning	Action
500 Internal Server Error	Unexpected error	Retry; contact support if it persists
502 Bad Gateway	Upstream dependency unavailable	Retry after a short delay
503 Service Unavailable	Temporarily unavailable	Retry after a short delay

Validation errors

A 422 response lists each field that failed validation under details.errors. Each entry names the field location (loc), a message (msg), and an error type. Fix the flagged fields and resubmit.

Handling errors in code

import requests

response = requests.get(
    "https://api.haltless.io/api/v1/machines",
    headers={"Authorization": f"Bearer {token}"},
)

if response.ok:
    machines = response.json()
elif response.status_code == 401:
    token = refresh_token()
    # retry with the new token
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", "5"))
    time.sleep(retry_after)
    # retry the request
else:
    error = response.json()
    message = error.get("detail") or error.get("message")
    print(f"Error {response.status_code}: {message}")