Integration troubleshooting

Diagnose URL, protocol, state, and result handling problems by symptom.

Reproduce with a minimal request using the same address, token, and model, then restore application parameters one at a time. Errors and retries explains status codes; this page covers cross-interface problems.

Symptom	Check first	Next step
HTML or page 404	Website root instead of API path, or duplicated /v1	Compare URL conventions; record the method and URL
Model list works but generation fails	Protocol, parameters, and current route availability	Remove tools/images, then validate each capability separately
Model lookup returns 200 without id	An error object	Handle business failure per the reference
SDK fails after uploading Files	Framework calling an unimplemented resource API	Use directly supported endpoint inputs; see coverage
Stream appears all at once	Proxy buffering, compression, or UI waiting for all text	Compare direct gateway access with the same request through the proxy
Empty or interrupted text	Refusal, tools, reasoning, length limits, incomplete state	Parse the correct protocol; see streaming
Incomplete tool argument JSON	Parsing or execution during deltas	Assemble by index / call_id and execute only after completion
Native multi-turn signature errors	Lost thinking, thoughtSignature, or original blocks	Preserve complete history; never reconstruct opaque signatures
Lost context after compaction	Kept only the compaction item, appended old history, or changed channels	Replay the whole window per the compaction guide
Background lookup returns 404	Platform plugin origin, user/project match, retained results	Use the original identity and inspect task state; do not recreate automatically
Moderation lacks results	Channel rebuilding a text response	Check moderation adaptation limits
RAG has unknown citations or unsupported answers	Candidate index mapping, document access, citation validation	Diagnose each stage with the RAG guide
Media download fails	Completed task, URL expiry, authorization, Range support	Separate task state from download state; do not immediately regenerate

Frequently asked questions

Can I just replace an official SDK’s Base URL? That is usually the starting point for supported endpoints using the same protocol. Also set the model explicitly and inspect hidden resource calls in frameworks. The migration checklist covers related changes.

Why not use one output parser for every endpoint? Chat uses choices, Responses uses output, Claude uses content blocks, Gemini uses candidates, and media can return bytes or tasks. Share HTTP error handling, but distinguish business completion and extraction by protocol.

Can I retry immediately after disconnection? First determine whether the request may have been accepted and whether you received partial output or a task ID. Query known tasks first. Handle uncertain results according to your application’s duplicate-risk policy. This site does not promise a universal idempotency key.

Do passing local example tests prove model availability? No. Fixtures test client protocol handling and failure paths. Actual access, model capabilities, generation quality, and encrypted-state replay require target-service acceptance.

Provide useful diagnostic information

Share non-sensitive details with the deployment maintainer: time and timezone, endpoint and method, model, SDK version, HTTP status, completion status, gateway request ID when available, a redacted minimal parameter structure, and expected versus actual behavior. Exclude tokens, cookies, signed URLs, complete media, and private user content. Keep reproductions small to limit requests.

阅读中文

Multimodal and parameter compatibility

Symptom	Cause and action
Base64 audio is rejected	Chat input_audio.data needs plain Base64 and the actual format, without a Data URL prefix. WAV markers do not establish acceptable sample rate, duration, or codec
Transcription works but audio Chat fails	Different endpoint capabilities; select an audio Chat model and send JSON per audio input
Video generation works but video analysis fails	Generation and understanding differ; use a native Gemini model supporting video, per video understanding
Gemini SDK calls upload/files and gets 404	Auto-upload is absent from audited gateway routes. Use supported small inlineData inputs or a deployment-confirmed file workflow; do not retry indefinitely
An upstream video_url object fails	The current Chat parser reads only the string branch. Raw forwarding and conversion differ; do not blindly copy OpenRouter’s shape
413 or interrupted media request	Base64 expands payloads. Check proxy, gateway, and upstream size/duration limits; reduce or transcode properly, not just rename extensions
Browser opens a URL but the model cannot	Servers lack browser cookies; signatures, redirects, expiry, networking, and account permissions can matter. Never append gateway keys to media links
prediction is rejected or gives no speedup	Check model, native Chat routing, and parameter combinations. Responses conversion has no mapping; absent stats do not establish zero acceptance. See predicted outputs
SDK rejects a documented field	SDK version or method types may restrict it. Isolate the problem with the matching HTTP example; bypassing client types does not establish upstream support

Request lifecycle questions

Does Stop always stop the server task? Client abort means it stops waiting or reading. It does not prove upstream work stopped, tasks were canceled, or charges cannot occur. Closing SSE is not a universal cancellation API. Query known task IDs first; the project also lacks a general Responses cancel endpoint.

Why do copied official examples call failing extra endpoints? Inspect SDK defaults, uploads, history retrieval, and retries. responses.create, Chat, Files, and Interactions are different resources. Use documented endpoints and the migration checklist.

Why does a sent parameter have no effect? Check SDK serialization, DTO representation, converter mapping, channel overrides/filtering, and upstream support separately. Add parameters one at a time to a minimal request and retain non-sensitive diagnostics. See parameter filtering.

Tool policy and JSON questions

Problem	Check
Invalid arguments despite strict	Current Chat/Responses function conversion omits strict; verify the actual path and always validate in the application
required keeps producing tools	Repeating required can keep requesting calls; after returning results, select none or a suitable policy when only a final answer is needed, and bound rounds
Multiple calls despite parallel disabled	Do not assume execution is safe; validate the whole call list before any execution, without partial tool execution or automatic replay
Selected function is ignored	Chat nests the name under function; Responses uses a sibling name. Check SDK serialization, conversion, and model support
JSON.parse succeeds but business validation fails	JSON mode does not enforce fields, enums, or types; distinguish null/missing, integer/string, and extra fields
Whitespace or truncated JSON	Explicitly request JSON; check format fields, model, and completion status. Do not append a retry’s output or repair brackets and call it success
Repeat tools after second-turn failure?	A tool may already have executed. Retain correlated calls/results and follow application recovery policy to prevent repeated mutations

Tool control example · JSON validation example

Gemini tools return text but no evidence

Enabling a built-in tool allows model use; it does not force execution for every prompt. Inspect groundingMetadata, urlContextMetadata, or codeExecutionResult for the chosen tool. If your workflow requires tool use, stop when evidence is absent. Do not silently present a direct answer as searched, retrieved, or executed.

Search citations point to the wrong characters

Gemini grounding segment offsets refer to UTF-8 bytes in the original part, with endIndex exclusive. Chinese and emoji expose mistakes from using JavaScript string slicing or joining parts first. Preserve partIndex and source ordering; validate byte boundaries and groundingChunkIndices before rendering. The built-in example does this for one non-streaming candidate.

URL retrieval fails or code execution reports an error

Check each URL retrieval status; a paywall, unsafe URL, different redirected URL, or missing metadata is not confirmed access. Code execution can fail or time out while the response remains HTTP 200. Inspect outcome and matching code/result parts. The example stops on any failed execution and never runs generated code locally. Custom function results belong to the function-calling loop, not codeExecutionResult.

A newer Gemini SDK example uses an unsupported route or loses tool state

Choose generateContent-compatible examples, not Interactions or Files management calls. Use camelCase native JSON keys; copying Python snake_case wire payloads may lose fields in the gateway DTO. Original response metadata can survive while newer unknown request fields are dropped on replay. Confirm the actual DTO and channel before enabling multi-turn tool combinations; see native tool scope.