Error Handling

All error responses follow a consistent format:

{
  "error": "Description of the error"
}

HTTP Status Codes

Status	Meaning	When
`400`	Bad Request	Missing required fields or invalid data
`401`	Unauthorized	Missing or invalid API key
`404`	Not Found	Agent, session, or resource doesn't exist
`500`	Internal Server Error	Unexpected server-side error

Common Errors

401 — Unauthorized

{
  "error": "Unauthorized. API key is missing or invalid."
}

Causes:

X-API-Key header is missing
API key is malformed (must start with api_)
API key has been revoked or expired
API key doesn't exist

Fix: Check your API key is correct and hasn't expired.

404 — Agent Not Found

{
  "error": "Agent not found"
}

Causes:

The agent ID is incorrect
The agent is not in PUBLISHED state
The agent belongs to a different organisation

Fix: Use GET /agents to list valid agent IDs.

404 — Session Not Found

{
  "error": "Session not found"
}

Causes:

The session ID is incorrect
The session was deleted
The session belongs to a different agent

400 — Missing Message

{
  "error": "Message is required and must be a non-empty string"
}

Fix: Ensure the message field is present and non-empty in the request body.

Handling Errors in Code

Error handling example

async function sendMessage(agentId: string, sessionId: string, message: string) {
  const res = await fetch(
    `http://localhost:3002/agents/${agentId}/sessions/${sessionId}/messages`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.API_KEY!,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ message })
    }
  );

  if (!res.ok) {
    const error = await res.json();

    switch (res.status) {
      case 401:
        throw new Error('Invalid API key. Check your credentials.');
      case 404:
        throw new Error(error.error); // "Agent not found" or "Session not found"
      case 400:
        throw new Error(`Bad request: ${error.error}`);
      default:
        throw new Error(`API error (${res.status}): ${error.error}`);
    }
  }

  return res.json();
}

HTTP Status Codes

Common Errors

401 — Unauthorized

404 — Agent Not Found

404 — Session Not Found

400 — Missing Message

Handling Errors in Code

On this page