spb/doc-api

This page provides a reference for all Interactions API error codes, describes the error response format, and explains how the API delivers errors for different request types.

# Standard API error codes

These general request-level error codes correspond to standard HTTP status codes. Use the code field in your application logic to handle errors programmatically.

[!NOTE] Note: Any error code not listed above falls back to the snake_case version of the HTTP status.

# Generation blocked codes

These error codes indicate that policy, safety, or content restrictions blocked the model's output. When you receive one of these codes, modify your input and retry.

# Generation error codes

These error codes indicate a structural issue with the model's generated output (such as a malformed function call or an undeclared tool call).

# Error response format

All errors from the Interactions API return an error object containing a code and message. For example, passing an unsupported tool type returns:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'. Supported values: 'function', 'code_execution', 'mcp_server', 'filesystem', 'google_maps', 'google_search', 'bash', 'computer_use', 'file_search', 'url_context'."
  }
}

# How errors are delivered

The API delivers errors differently depending on whether you make a standard HTTP request or a streaming (SSE) request.

# Standard HTTP requests

For standard (non-streaming) requests, the API sets the HTTP response status code (such as 400 Bad Request, 401 Unauthorized, or 429 Too Many Requests) and returns an error object in the JSON response body:

{
  "error": {
    "code": "invalid_request",
    "message": "The value 'invalid_tool_type_xyz' is not supported for 'type' at 'tools[0]'."
  }
}

# Streaming (SSE) requests

For streaming requests (stream: true), the API sends error events over the Server-Sent Events (SSE) stream with event_type set to "error". The error field contains the same code and message structure:

{
  "event_type": "error",
  "error": {
    "code": "not_found",
    "message": "Failed to get completed interaction: Result not found."
  }
}

For the full SSE event schema, see the Interactions API Reference.

# What's next

• API troubleshooting: Resolve common issues and error scenarios.
• Rate limits: Learn about request limits and quota handling.