Advanced

Error Handling

Understand error responses, status codes, and how to handle failures in both REST API calls and Server-Sent Events streams.

Error Response Format

All HTTP errors follow a consistent JSON format:

json

{
  "error": "Error message describing what went wrong",
  "statusCode": 400
}

Common Status Codes

Code	Meaning	Common Causes
`400`	Bad Request	Missing required fields, invalid JSON format
`401`	Unauthorized	Invalid or missing API key, expired embed token
`403`	Forbidden	Domain restriction violation (embed tokens), insufficient permissions
`404`	Not Found	Invalid agentId, environmentId, or threadId
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Server Error	Unexpected server issue, tool execution failure

SSE Error Events

Errors during streaming are sent as error events before the stream closes:

json

// Error event in SSE stream
{
  "type": "error",
  "error": "Tool execution failed: API endpoint returned 500",
  "isComplete": true
}

Handling SSE Errors in JavaScript

javascript

const reader = response.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

try {
  while (true) {
    const {value, done} = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, {stream: true});
    const lines = buffer.split('\n\n');
    buffer = lines.pop() || '';

    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const event = JSON.parse(line.slice(6));

        if (event.type === 'error') {
          console.error('Stream error:', event.error);
          // Show error to user
          showErrorMessage(event.error);
          return; // Stream ends after error
        }

        // Handle other events...
      }
    }
  }
} catch (error) {
  console.error('Connection error:', error);
  showErrorMessage('Connection lost. Please try again.');
}

Troubleshooting Tips

401 Unauthorized

✓ Verify API key is correct and not expired
✓ Check X-API-Key header is properly set
✓ For embed chat, verify embed token is valid
✓ Ensure API key matches the environment

403 Forbidden (Embed Tokens)

✓ Check parentDomain matches embed token restrictions
✓ Verify domain wildcard patterns (*.example.com)
✓ Ensure token hasn't expired
✓ Test from allowed domain

404 Not Found

✓ Verify agentId exists in the environment
✓ Check environmentId is correct
✓ Confirm agent is active (not deleted)
✓ For threadId errors, verify thread exists

500 Internal Server Error

✓ Check traceId in logs for debugging
✓ Verify tool endpoints are accessible
✓ Ensure backend token (if provided) is valid
✓ Review agent system instructions for issues
✓ Contact support if error persists

Always capture the traceId from complete or error events for debugging. Include it when contacting support.

PreviousOutput Schemas NextScreen Observer

Last updated: March 2026Report an issue