API Troubleshooting and Security

Start with cURL, Then Test the Client

Keep the current client and key, then establish a comparable baseline with a minimal request. This helps determine whether the issue is in the API, protocol, client, or local network.

1. Record: Save the UTC time, client version, model, protocol, full error message, and redacted URL.
2. Minimal request: Send a non-streaming cURL request with only the model and one text input; remove reasoning effort, tools, and structured output.
3. Compare: If cURL fails, follow the API status code. If cURL succeeds but the client fails, check the provider, path construction, environment variables, and proxy.
4. Restore parameters: After the text request succeeds, add streaming, structured output, and tool calls one at a time.

Minimal Request

-i prints both response headers and the response body, preserving the status code and X-Request-ID. The examples read the key from the KHAIX_API_KEY environment variable; change the client request ID to a unique value for this troubleshooting session.

curl -i --max-time 60 https://api.khaix.net/v1/responses \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-ID: diag-20260717-001" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Reply with only: connection successful"
  }'

If the client uses Chat Completions, test that protocol with the same key and model:

curl -i --max-time 60 https://api.khaix.net/v1/chat/completions \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Request-ID: diag-20260717-002" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      {"role": "user", "content": "Reply with only: connection successful"}
    ]
  }'

An HTTP 200 response, text in the response body, and a matching console record confirm that the protocol path is working. Confirm the model ID through GET https://api.khaix.net/v1/models or the live list in the console.

HTTP Status Codes

400 or 422: Invalid Request Format

• Responses request bodies use input; Chat Completions uses messages.
• Temporarily remove reasoning effort, tools, and structured output, leaving only the model and one text input.
• Check JSON quotes, commas, field types, and proprietary parameters automatically added by the client.
• If the error mentions an unknown field, verify the provider protocol and final endpoint.

401: Authentication Failed

• Check that the API Key is complete, especially for leading or trailing spaces, newlines, or truncation by logging tools.
• The authentication header for OpenAI-compatible requests must be Authorization: Bearer YOUR_API_KEY.
• Place configuration files and environment variables in the user account, container, WSL environment, or remote host where the client actually runs.
• If requests still go to api.openai.com, the custom Base URL has not taken effect.

403: Insufficient Permissions

This usually means the key is valid, but the account, group, or model lacks request permission. Check the key scope, live model status, and console records. Creating another key of the same type will not change permissions.

404: Request Path Not Found

First inspect the URL actually requested by the client. Common errors include /v1/v1, /responses/responses, or entering a complete endpoint as the Base URL. The final path for Responses is /v1/responses; for Chat Completions, it is /v1/chat/completions.

413: Request Body Too Large

The current gateway request-body limit is 25 MB. Shorten the conversation history and reduce embedded text and attachment data before retrying. Increasing the client timeout does not resolve this error.

429: Quota or Rate Limit

Check the account balance, key quota, group rate limit, and console records. If quota is available, retry with exponential backoff and random jitter, and avoid replaying the same request concurrently. If the issue continues, retain the request IDs and UTC time.

500, 502, or 503: Service Path Failure

Send a minimal non-streaming request with the same model. If multiple clients fail at the same time, contact support with the request time, model, and request IDs. If only one client fails, first check its protocol, additional fields, and local proxy.

Streaming and Timeouts

After a non-streaming request succeeds, use -N to disable cURL output buffering and observe whether the SSE stream continues to a normal completion:

curl -N --max-time 180 https://api.khaix.net/v1/responses \
  -H "Authorization: Bearer $KHAIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "input": "Explain how to design an API retry strategy in five points",
    "stream": true
  }'

• cURL works, but the client stream disconnects: Check the client's SSE parsing, read timeout, and whether it waits for a complete response as ordinary JSON.
• The stream disconnects only through a proxy: Check reverse-proxy buffering, idle timeouts, connection reuse, and egress IP switching.
• The connection closes after a fixed interval: A client, gateway, or enterprise-proxy timeout is usually responsible.
• An error occurs inside the stream: An initial HTTP 200 does not mean the entire stream succeeded. Record the last complete event and its error fields.

Two Request IDs

Request IDs are for tracing only. Do not include an API Key, prompt, complete response, or personal information. You can use a UUID or an environment + date + random-string format. Whether retries of the same logical request reuse a client ID depends on your application's idempotency and logging strategy.

Use -i with cURL to view response headers. SDKs can read headers from the raw response or exception object. If the client does not display response headers, record the corresponding identifier from the console request record.

Include These Details When Contacting Support

• Time: The request's UTC time and local time zone, accurate to the minute.
• Tracing: The X-Request-ID, X-Client-Request-ID, and console record identifier.
• Environment: The client or SDK name, exact version, operating system, and whether WSL, a container, or a remote host is involved.
• Request: The model ID, protocol, whether streaming was enabled, and the redacted URL actually requested.
• Error: The HTTP status code, complete error message, and last streaming event.
• Baseline: Whether the minimal cURL request succeeded and whether the issue occurs only with a specific client, streaming, or tool call.

Security Considerations

Key Security

• Use separate keys for each application, environment, and team. Revoke and rotate a key immediately if exposure is suspected.
• Store keys in environment variables, the system keychain, or deployment-platform secrets; do not commit them to a repository.
• Browser frontends, public scripts, and distributable clients must not contain long-lived keys.
• Logs should hide Authorization headers and authentication configuration by default.

Execution Security

• Keep individual confirmation enabled for a coding agent's file changes, command execution, network access, and external-tool permissions.
• Keep --yolo, YOLO Mode, and blanket Auto-Approve disabled in untrusted projects.
• Use a low-privilege account, container, or virtual machine for high-risk tasks, and limit the working directory and credential visibility.
• Before retrying after a stream disconnect or client failure, confirm whether the tool already ran.

Proxy Security

• Expose local protocol converters, debugging proxies, and unauthenticated ports only on controlled networks.
• Enterprise proxies and self-hosted reverse proxies must verify TLS, restrict administration ports, and disable logging of Authorization headers and request bodies.
• Set proxy buffering, maximum request-body size, connection timeouts, and idle timeouts explicitly. Fix certificate trust chains instead of disabling TLS verification.
• After troubleshooting, remove temporary packet-capture certificates, global proxies, and detailed logs containing sensitive data.

Data Security

• Prompts and model responses are processed by KHaiXAPI and the corresponding upstream service during the request. Remove credentials and personal information unrelated to the task.
• KHaiXAPI does not write prompts or model responses to business storage. See the Privacy Policy for request and billing metadata and upstream processing boundaries.
• Third-party clients may store conversations, telemetry, or logs independently. Review their data settings and storage locations before use.
• Production systems require access control, content validation, auditing, and retention-period management for inputs and outputs.