Skip to content

Error Handling

This page documents the error behaviors currently implemented by the REST API (mainly /api/v2).

Error Response Formats

The API currently uses three response patterns:

1. FastAPI HTTPException format

{
  "detail": "<message>"
}

Used by authentication middleware and several endpoints.

2. Route-level error payloads

{
  "error": "<message>",
  "status": "<optional status>",
  "head_error": "<optional details>",
  "base_error": "<optional details>"
}

Used by routes that set response.status_code directly (for example network and SSH key endpoints).

3. Logical error in successful HTTP response

Some endpoints can return an error object while keeping HTTP 200. For example, service endpoints may return {"result": "Error: ..."}. Some SSH endpoints can also return {"error": "Unauthorized access level."} with HTTP 200. Clients should check response content, not only status code.

Real HTTP Status Codes Used

307 Temporary Redirect

Used by camera-manager proxy routes.

400 Bad Request

Used for invalid client input such as:

  • Map texture URL validation failures (Only http/https URLs are supported, Invalid map texture URL, Map texture host is required, Unsupported map image extension, Unsupported map texture port, Map texture host is not allowed).
  • Skill upload with invalid filename (Only '.py' files are allowed, optionally prefixed with 'disabled.').
  • SSH key operations with invalid key format, missing/invalid key id, or missing fingerprint.
  • Wi-Fi configuration errors caused by invalid/incomplete client parameters (returned as {"error": "..."}).

401 Unauthorized

Authentication/JWT/API-key related errors:

  • Authorization header missing
  • Invalid authorization type
  • Invalid authorization header format
  • Token has expired
  • Invalid token
  • Not authenticated
  • Missing API Key for TCP connection.
  • Invalid API Key
  • Access level required for TCP clients.

403 Forbidden

Authorization and access-level checks:

  • Invalid access level in token.
  • Unauthorized access level.

Also used by mesh download when file type is rejected:

  • Unsupported file type

404 Not Found

Resource-specific missing data examples:

  • Mesh retrieval: Mesh file not found: <filepath>
  • URDF base path unavailable: URDF path not set
  • Database load item not found (detail propagated from backend result)
  • Wi-Fi remove route when SSID is unknown (returned as {"error": "No configured network found for SSID '...'"})

422 Unprocessable Entity

Automatically returned by FastAPI/Pydantic for invalid path/query/body schemas. Example cases include wrong field types or missing required fields.

500 Internal Server Error

Used for unexpected backend/runtime failures across multiple endpoints, for example:

  • Impossible to verify API key.
  • Failed to get volume.
  • Could not parse volume.
  • Failed to save the skill.
  • Database operation failures (Internal Server Error: ...)
  • URDF/mesh internal exceptions (Internal Server Error: ...)
  • SSH and Wi-Fi command execution failures (often returned as {"error": "..."}).

502 Bad Gateway

Used by map-texture proxy when upstream fetch fails:

  • Failed to fetch map texture: <upstream details>

503 Service Unavailable

Used by middleware when a request is cancelled during shutdown:

  • Server is shutting down

Authentication Error Header

For 401 responses emitted by JWT middleware, the API includes:

  • WWW-Authenticate: Bearer

Client Handling Recommendations

  1. For non-2xx responses, read the detail field when present.
  2. For 200 responses, also inspect error, status, and result fields.
  3. Treat 401 as re-authentication required (refresh token or request a new one).
  4. Treat 5xx as retryable only when the operation is idempotent.