Timeout, Forbidden Parameters, and Configuration

Updated November 3, 2026. Based on xAI best practices and the Reasoning guide: the recommended wait time is at least 900 seconds (3,600 in examples), not “3,600 seconds minimum”; the reasoning model list includes grok-4.6 and grok-4.7; grok-4.7 streams a summary of its reasoning; justifications for forbidden parameters, absent from the documentation, are removed. Sources: Best practices · Reasoning.

Configure your reasoning requests correctly

Reasoning models have specific constraints that classic models do not. Ignoring these constraints can cause silent errors, unexpected timeouts, or truncated responses. This lesson covers essential configuration parameters.

Timeout: at least 900 seconds

xAI best practices require at least 900 seconds per request, and 1,800 seconds or more for long evaluations; the Reasoning guide examples even set the delay to 3,600 seconds (1 hour). These numbers may seem high, but they reflect reality: deep reasoning on a complex problem can take several minutes. xAI also recommends preferring streaming, which keeps the connection active during long generations.

Why such a long timeout?

When a reasoning model processes a difficult problem (math proof, complex code analysis, multi-step reasoning), it potentially generates thousands of internal reasoning tokens before formulating its response. This process is linear and cannot be parallelized.

Timeout configuration

import httpx
from openai import OpenAI

# Configuration with high timeout
client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.x.ai/v1",
    timeout=httpx.Timeout(3600.0, connect=10.0)
)

In JavaScript with the OpenAI SDK:

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'your-api-key',
  baseURL: 'https://api.x.ai/v1',
  timeout: 3600 * 1000  // 3600 seconds in milliseconds
});

Web server timeout

If your application is behind a reverse proxy (nginx, Apache), also configure the server-side timeout:

# nginx
location /api/ {
    proxy_read_timeout 3600s;
    proxy_connect_timeout 10s;
    proxy_send_timeout 3600s;
}

Forbidden parameters on reasoning models

Three parameters commonly used with classic models cannot be sent to xAI reasoning models: according to the Reasoning guide, a request containing them returns an error. The documentation does not give the reason for these prohibitions; remember the rule.

presencePenalty

// ERROR on reasoning models
{
  "model": "grok-4.20-0309-reasoning",
  "presence_penalty": 0.5,  // Forbidden!
  "messages": [...]
}

presencePenalty penalizes tokens that already appeared in the response to encourage diversity.

frequencyPenalty

// ERROR on reasoning models
{
  "model": "grok-4.20-0309-reasoning",
  "frequency_penalty": 0.3,  // Forbidden!
  "messages": [...]
}

frequencyPenalty penalizes tokens proportionally to their frequency of appearance.

stop

// ERROR on reasoning models
{
  "model": "grok-4.20-0309-reasoning",
  "stop": ["\n\n"],  // Forbidden!
  "messages": [...]
}

The stop parameter stops generation when a specific sequence appears. To bound response length, use max_completion_tokens instead, which caps only the visible response, and a format instruction in the prompt.

Handling parameter-related errors

When migrating existing code to a reasoning model, clean up unsupported parameters:

def prepare_params(model, base_params):
    """Cleans parameters for reasoning models."""
    reasoning_models = [
        # current range
        "grok-4.7", "grok-4.6", "grok-4.5", "grok-4.20-0309-reasoning",
        # historical identifiers, still present in existing code
        "grok-3-mini", "grok-4-fast-reasoning",
    ]

    params = {**base_params, "model": model}

    if model in reasoning_models:
        # Remove forbidden parameters
        for forbidden in ["presence_penalty", "frequency_penalty", "stop"]:
            params.pop(forbidden, None)

        # Replace max_tokens with max_completion_tokens
        if "max_tokens" in params:
            params["max_completion_tokens"] = params.pop("max_tokens")

    return params

Streaming with reasoning models

Streaming works with reasoning models, but behavior depends on generation: on grok-3-mini (previous generation), reasoning_content appeared in clear in the stream, before response tokens. On grok-4.20-0309-reasoning, reasoning remains internal and is not streamed: only the final response arrives in the stream. Notable exception: on the Responses API, grok-4.7 streams a summary of its reasoning, in response.reasoning_summary_text.delta events that you can display before the response.

Historical example with grok-3-mini:

stream = client.chat.completions.create(
    model="grok-4.20-0309-reasoning",
    messages=[{"role": "user", "content": "Why is the sky blue?"}],
    reasoning_effort="high",
    stream=True
)

for chunk in stream:
    delta = chunk.choices[0].delta
    if hasattr(delta, 'reasoning_content') and delta.reasoning_content:
        print(f"[Reasoning] {delta.reasoning_content}", end="")
    elif delta.content:
        print(f"[Response] {delta.content}", end="")

Key takeaways

• Allow at least 900 seconds per request (3,600 in Reasoning guide examples), and prefer streaming
• Three parameters are forbidden: presencePenalty, frequencyPenalty, and stop
• Clean parameters when migrating from classic models
• Use max_completion_tokens instead of max_tokens
• Streaming works but behavior differs by model