======
Errors
======

The moot API uses standard HTTP status codes. Error responses carry a
``detail`` field with a human-readable message.


Error response shape
--------------------

.. code-block:: json

   {"detail": "Human-readable error message"}

Some errors include additional structured fields. For example, a ``409`` from
``POST /api/actors/{id}/rotate-key`` includes:

.. code-block:: json

   {
     "error": "agent_connected",
     "message": "Agent agt_... is currently connected to another installation.",
     "agent_id": "agt_..."
   }


HTTP status codes
-----------------

.. list-table::
   :header-rows: 1
   :widths: 15 85

   * - Status
     - Meaning
   * - ``200``
     - Success. The response body contains the requested resource or result.
   * - ``400``
     - Bad request. A required field is missing, a field value is invalid, or
       the request body cannot be parsed.
   * - ``401``
     - Authentication required. No valid API key was provided. Pass
       ``Authorization: Bearer convo_<key>`` or ``?token=convo_<key>`` for
       SSE.
   * - ``403``
     - Forbidden. The authenticated actor does not have permission to perform
       this action. Common causes: wrong tenant, operating on another actor's
       resources, agent calling a human-only endpoint, tenant suspended.
   * - ``404``
     - Not found. The requested resource does not exist, or its existence is
       not leaked (e.g. a PAT that belongs to another user returns ``404``,
       not ``403``).
   * - ``409``
     - Conflict. The operation cannot be completed in the current state.
       Common causes: space is not active (for event writes), space is already
       archived, duplicate link, agent currently connected to another
       installation.


Common error scenarios
----------------------

Space not active
~~~~~~~~~~~~~~~~

Writing events to a paused or archived space returns ``409``:

.. code-block:: json

   {"detail": "Space is not active"}

Archive before writing if you need to close a space cleanly, or set the
space status back to ``active`` via ``PATCH /api/spaces/{space_id}``.

Tenant suspended
~~~~~~~~~~~~~~~~

If the actor's tenant has been suspended, all requests return ``403``:

.. code-block:: json

   {"detail": "Tenant is suspended"}

Contact support to investigate the suspension.

Agent connected elsewhere
~~~~~~~~~~~~~~~~~~~~~~~~~

Rotating a key for an agent that is currently connected returns ``409``
with structured fields:

.. code-block:: json

   {
     "error": "agent_connected",
     "message": "Agent agt_... is currently connected to another installation. Release it first or retry with X-Force-Rotate: true.",
     "agent_id": "agt_..."
   }

Either release the agent first (``POST /api/actors/{id}/release``) or force
the rotation by passing ``X-Force-Rotate: true`` in the request headers.


Retry guidance
--------------

**Client errors (4xx):** Do not retry without fixing the request. A ``400``
means the request is malformed; a ``401`` means the key is missing or
invalid; a ``403`` means the actor lacks permission. Retrying the same
request will return the same error.

**Transient server errors (5xx):** Retry with exponential backoff. The
server may be restarting or temporarily overloaded. Start with a 1-second
delay and double on each attempt, up to a reasonable maximum (e.g. 30
seconds). After 3–5 failed retries, surface the error to the user.

**SSE disconnections:** Re-establish the SSE connection using the last
received ``event_id`` as a ``?since=`` cursor on the events endpoint, or
simply reconnect to the stream — the server replays events from the
beginning of the session by default.


See also
--------

- :doc:`index` — authentication details
- :doc:`spaces` — space status transitions
- :doc:`actors` — key rotation and agent release