Common errors

Keyword: What errors will I encounter during SmartTouch developer onboarding?

This reference covers every error you are likely to encounter while working through the First API call journey and during normal development. Each entry includes the HTTP status code (for REST API calls), the error message, the cause, and the fix.

---

Quick lookup table

HTTP status	Error code	Where it occurs	Go to
401	unauthorized	Any API call	401 Unauthorized
403	forbidden	Opening a session	403 Forbidden
404	not_found	Get device, get session	404 Not Found
409	conflict	Opening a session	409 Conflict
422	unprocessable_entity	Opening a session	422 'Unprocessable Entity'
429	rate_limited	Any API call	429 Rate Limited
500	internal_error	Any API call	500 Internal Error
—	'stctl' errors	CLI commands	'stctl errors'

---

401 Unauthorized

HTTP status: 401

Response body:

{
  "error": "unauthorized",
  "message": "Bearer token is missing or has expired.",
  "status": 401
}

Occurs at: Every API endpoint when the Authorization header is missing, malformed, or contains an expired token.

Causes and fixes:

Cause	Fix
$TOKEN variable is empty	Run TOKEN=$(stctl auth token) and verify echo $TOKEN prints a value
Token has expired (8-hour lifetime)	Run TOKEN=$(stctl auth token) to refresh
Authorization header typo	Confirm the header is exactly Authorization: Bearer <token> with a capital A and a space between Bearer and the token
Service account token was revoked	Ask your Administrator to issue a new service account token

Example fix:

# Re-export a fresh token
TOKEN=$(stctl auth token)

# Retry the failed request
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.smarttouch.local/v1/devices"

---

403 Forbidden

HTTP status: 403

Response body:

{
  "error": "forbidden",
  "message": "Your role does not permit shell sessions. Required role: platform-engineer.",
  "status": 403
}

Occurs at: POST /remote-access/sessions when the authenticated user's role doesn't meet the minimum requirement for the requested protocol.

Protocol role requirements:

Protocol	Minimum role
diagnostics	developer
shell	platform-engineer
file-transfer	administrator

Causes and fixes:

Cause	Fix
Requesting shell with a developer role	Use "protocol": "diagnostics" instead, or ask a Platform Engineer to open the shell session
Requesting file-transfer with a developer role	Ask an Administrator to perform the file transfer
Account role not yet assigned	Ask your Administrator to assign the correct role

Verify your current role:

stctl auth status

---

404 Not Found

HTTP status: 404

Response body:

{
  "error": "not_found",
  "message": "Device not found: onboarding-device-99",
  "status": 404
}

Occurs at: GET /devices/{id}, GET /devices/{id}/agent-status, POST /remote-access/sessions.

Causes and fixes:

Cause	Fix
Device ID is misspelled	Run stctl device list to see the exact registered IDs
Device has never connected to the platform	Provision the device and install the Remote Access Agent—See Connect a device for remote access
Device was deleted from the platform	Ask your Administrator to re-register the device
Simulator isn't running	Run stctl simulator start --device-id onboarding-device-01 --remote-access

Find the correct device ID:

stctl device list --env dev

---

409 Conflict

HTTP status: 409

Response body:

{
  "error": "conflict",
  "message": "A diagnostics session is already open for device onboarding-device-01.",
  "status": 409
}

Occurs at: POST /remote-access/sessions.

Cause: Only one session per protocol per device can be open at a time. A session was opened earlier and not closed.

Fix: List open sessions, find the existing session, and close it before opening a new one.

# List open sessions for the device
stctl remote-access list --device onboarding-device-01 --status open

# Close the existing session
stctl remote-access close <session_id>

# Retry opening a new session
stctl remote-access open onboarding-device-01 --protocol diagnostics

REST API equivalent:

# List open sessions
curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.smarttouch.local/v1/remote-access/sessions?device_id=onboarding-device-01&status=open"

# Close the existing session
curl -s -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.smarttouch.local/v1/remote-access/sessions/<session_id>"

---

422 'Unprocessable' Entity

HTTP status: 422

Response body:

{
  "error": "unprocessable_entity",
  "message": "Cannot open session: device agent is offline.",
  "status": 422
}

Occurs at: POST /remote-access/sessions.

Cause: The request is valid but cann't be completed because the device agent isn't connected to the session broker. The device appears in the platform but isn't reachable.

Fix:

1. Verify the agent status:

stctl device agent-status onboarding-device-01

1. If agent_status is offline, check whether the agent process is running on the device:

# On the device
systemctl status smarttouch-agent

1. If the agent is stopped, start it:

# On the device
systemctl start smarttouch-agent

1. Wait 15 seconds, then check agent status again:

stctl device agent-status onboarding-device-01

1. Retry opening the session once agent_status returns online.

For detailed device connection troubleshooting, see Why is my device not connecting?.

---

429 Rate Limited

HTTP status: 429

Response body:

{
  "error": "rate_limited",
  "message": "Too many requests. Retry after 42 seconds.",
  "status": 429
}

Response header: Retry-After: 42

Occurs at: Any API endpoint when the rate limit for that endpoint group is exceeded.

Rate limits:

Endpoint group	Limit
GET /devices	120 requests per minute
POST /remote-access/sessions	30 requests per minute
GET /audit/remote-access	60 requests per minute

Fix: Wait the number of seconds in the Retry-After header before retrying.

In scripts, implement exponential 'backoff':

# Simple retry with backoff
RETRY_AFTER=$(curl -sI \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.smarttouch.local/v1/devices" \
  | grep -i "retry-after" | awk '{print $2}' | tr -d '\r')

sleep ${RETRY_AFTER:-5}

Rate limits apply per user, not per device. If you are scripting many session opens in quick succession, add a sleep 2 between calls.

---

500 Internal Error

HTTP status: 500

Response body:

{
  "error": "internal_error",
  "message": "An internal error occurred. Request ID: req-abc123.",
  "status": 500
}

Occurs at: Any API endpoint.

Cause: An unexpected error in the SmartTouch platform itself.

Fix:

1. Check the platform status page or run stctl status --env dev.
2. If the platform is healthy, retry the request after 30 seconds—The error may be transient.
3. If the error persists, contact your Platform Engineer with the Request ID from the response body.

---

'stctl' errors

stctl: command not found

stctl isn't installed or not on your PATH. See Prerequisites for installation instructions.

---

Error: authentication required

You aren't logged in. Run:

stctl auth login

---

Error: device not found: <device_id>

The device ID doesn't exist or was mistyped. Run stctl device list to see registered device IDs.

---

Error: session already open for protocol diagnostics

Equivalent to HTTP 409 Conflict. List and close the existing session:

stctl remote-access list --device <device_id> --status open
stctl remote-access close <session_id>

---

Error: forbidden — your role does not permit shell sessions

Equivalent to HTTP 403. Use --protocol diagnostics or contact your Platform Engineer.

---

Error: context deadline exceeded

The request timed out. This usually means the platform API isn't reachable from your network. Verify your network can reach the API endpoint:

curl -s "https://api.smarttouch.local/v1/devices" --max-time 5

If this fails, check your VPN connection or ask your Platform Engineer to confirm the platform URL.

---

Error handling in scripts

When calling the REST API from scripts, check the HTTP status code before processing the response body:

HTTP_STATUS=$(curl -s -o /tmp/response.json -w "%{http_code}" \
  -H "Authorization: Bearer $TOKEN" \
  "https://api.smarttouch.local/v1/devices/onboarding-device-01/agent-status")

if [ "$HTTP_STATUS" -ne 200 ]; then
  echo "Error $HTTP_STATUS:"
  cat /tmp/response.json
  exit 1
fi

cat /tmp/response.json

---

Related

• First API call
• Authentication
• Why is my device not connecting?
• SmartTouch REST API reference—Error codes