Skip to content

Error Handling

How to handle and recover from API errors.

HTTP 400: Connection Not Found

{
  "detail": "Connection not found"
}

Meaning: The API server cannot find an active WebSocket connection matching the websocket_id you provided in the URL.

Recovery Strategy:

  1. Check WebSocket ID: Verify the ID in your code matches the one currently displayed in the extension popup. Reinstalling the extension generates a new ID.
  2. Verify Connection: Ensure the extension popup shows Connected ✓.
  3. Heartbeat: The extension sends heartbeats to keep the connection alive. If the computer went to sleep, the connection might be closed. Waking the computer and opening Chrome should auto-reconnect it.

HTTP 504: Request Timeout

{
  "detail": "Request to extension timed out"
}

Meaning: The request was sent to your browser, but no response was received within 60 seconds.

Common Causes:

  • Complex Query: Google AI Mode is "thinking" for too long.
  • Browser Lag: Chrome is frozen or under heavy load.
  • Network Drop: The connection dropped during the request.

Recovery Strategy:

  • Retry: Implement a retry loop with exponential backoff (wait 2s, then 4s).
  • Simplify: Try asking a shorter or simpler question.

HTTP 500: Server Error

Meaning: An internal error occurred on the relay server.

Recovery Strategy:

  • Retry: These are usually transient. Wait 5-10 seconds and try again.

Content Issues (200 OK but bad content)

Sometimes the API returns 200 OK, but the content isn't what you expected.

"I can't answer that" / Empty Answer

Google AI Mode has safety filters and limitations. If it refuses to answer, the API will return whatever text Google provided (or an empty string if it failed to render).

Strategy:

  • Check response_body length. If < 50 characters, flag for manual review.
  • Refrain from asking sensitive, political, or prohibited topics that trigger safety filters.