Errors

AISquare uses standard HTTP status codes to signal success or failure. An error response means authentication failed, input was invalid, access was restricted, or a resource was not found. This page lists the codes and how to handle each.

Status codes

401 Unauthorized

Returned when authentication is missing, the token or API key is invalid, or the session has expired.

Handling. Make sure credentials are included, verify the token or key, and re-authenticate if needed. See Token lifecycle for the refresh flow.

403 Forbidden

Returned when the user lacks the required role, or the endpoint is restricted (for example, owner-only metrics).

Handling. Verify the user's role and access level. See Permissions.

404 Not Found

Returned when a resource does not exist, a publication is invalid, or access to a non-public resource is restricted.

Handling. Verify identifiers (id, url, username) and confirm the user has access.

400 Bad Request

Returned when required fields are missing, the request format is invalid, or query parameters are incorrect.

Handling. Validate the request body, ensure required fields are present, and check parameter formats before sending.

409 Conflict — trace ingest

Returned by the explainability trace-ingest endpoint when a span batch cannot be routed to an agent. The response carries a machine-readable code in detail.code; branch on the code, not the message.

no_agent_identity

A root span arrived carrying no agent identity. The gateway routes each trace by (workspace, agent name), so a nameless root span has nowhere to go.

Handling. Fix the integration: name the agent (AgentRunTracer(agent_name=...), Agent(name=...) for Agno, metadata={"agent_name": ...} for LangChain, or X-Agent-Name on the proxy). Retrying will not succeed — the batch is rejected until it carries a name.

awaiting_trace_route

A child-only batch arrived before the root span that names its trace. The gateway cannot route children until the root establishes the identity.

Handling. Transient. The SDK retries the batch automatically once the root lands; no action needed unless it persists.

agent_not_registered

The trace carries a name, but that agent is not registered in the workspace.

Handling. Register the agent: PUT /api/v2/iam/workspaces/{ws}/agents/{name}/, or the dashboard's Connectors -> Agents "Register agent" button. Or avoid the case entirely: pre-register your roster with EXPLAINABILITY_AGENTS, or enable auto-discovery (autoregister_unknown_agents) on the workspace.

500 Internal Server Error

Returned on an unexpected failure on the server.

Handling. Retry if appropriate, log the error for debugging, and contact Support if it persists.

Endpoint-specific behavior

A few endpoints have notable error behavior:

• The permission endpoint may return 404 for access denial.
• The metrics endpoint returns 403 for unauthorized users.
• Collection and publication endpoints return 400 when the url is missing.

Best practices

• Validate inputs first. Avoid unnecessary 400 errors.
• Handle auth failures centrally. Put retry and re-auth logic in one place.
• Do not assume 404 means missing. It can indicate restricted access.
• Log errors. Capture status codes and responses for debugging.

Next steps