Error Reference

All Octomil API errors return a consistent JSON shape:

{
  "error": "error_code",
  "message": "Human-readable description of the problem.",
  "status_code": 400
}

HTTP Status Codes

Status	Error Code	Description	Resolution
400	bad_request	Invalid or missing request fields	Check request body against the API reference. Validate required fields and types.
401	unauthorized	Missing or invalid API key / token	Verify the Authorization header contains a valid key. Check key expiry and scopes.
403	forbidden	Insufficient permissions	The authenticated key lacks the required scope. Create a key with the needed scopes or use an admin key.
404	not_found	Resource does not exist	Verify the resource ID. The resource may have been deleted or belong to a different organization.
409	conflict	Resource already exists or state conflict	A resource with the same identifier exists, or the operation conflicts with the current state (e.g., starting a round while one is in progress).
422	validation_error	Request is well-formed but semantically invalid	Check field constraints (e.g., epsilon must be positive, trim_ratio must be between 0 and 0.5).
429	rate_limited	Too many requests	Wait for the duration specified in the Retry-After header. Control plane: 100 req/min per device.
500	internal_error	Unexpected server error	Retry with exponential backoff. If persistent, contact support with the X-Request-Id header value.
503	service_unavailable	Server is temporarily overloaded	Retry after a brief delay. Check status.octomil.com for incidents.

Common Error Scenarios

Device registration fails with 409

The device ID is already registered. Each device ID must be unique within an organization. If re-registering after a factory reset, revoke the old device first:

octomil devices revoke <device-id>

Training round fails with 400: insufficient_clients

Not enough eligible devices are online. Ensure min_devices_per_round does not exceed the number of connected devices. Check device status:

octomil devices list --status online

Model upload fails with 413: payload_too_large

Model file exceeds the upload size limit (default: 2 GB). Use model compression or chunked upload:

octomil models upload --model-id my-model --file large-model.pt --chunked

API key returns 401 after working previously

The key may have been rotated or revoked. Check the audit log for key lifecycle events:

octomil audit-log list --filter "api_key"

Rollout stuck in pending state

No eligible devices match the rollout's targeting criteria. Check device group membership and device connectivity:

octomil rollouts get <rollout-id>
octomil devices list --group <target-group> --status online

SDK Error Handling

All SDKs surface API errors as typed exceptions:

# Python
from octomil.exceptions import OctomilError, RateLimitError

try:
    client.models.list()
except RateLimitError as e:
    time.sleep(e.retry_after)
    client.models.list()
except OctomilError as e:
    print(f"{e.status_code}: {e.error} - {e.message}")

// iOS
do {
    let models = try await client.models.list()
} catch OctomilError.rateLimited(let retryAfter) {
    try await Task.sleep(nanoseconds: UInt64(retryAfter) * 1_000_000_000)
    let models = try await client.models.list()
} catch let error as OctomilError {
    print("\(error.statusCode): \(error.message)")
}