> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/en/guides/errors) 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](/en/guides/api-basics); 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](/en/api-reference/model-retrieve) |
| SDK fails after uploading Files | Framework calling an unimplemented resource API | Use directly supported endpoint inputs; see [coverage](/en/guides/api-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](/en/guides/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](/en/guides/compaction) |
| 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](/en/guides/moderations) |
| RAG has unknown citations or unsupported answers | Candidate index mapping, document access, citation validation | Diagnose each stage with the [RAG guide](/en/guides/rag) |
| 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](/en/guides/sdk-migration) 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.

[阅读中文](/zh/guides/troubleshooting)

## 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](/en/guides/audio-input) |
| Video generation works but video analysis fails | Generation and understanding differ; use a native Gemini model supporting video, per [video understanding](/en/guides/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](/en/guides/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](/en/guides/sdk-migration).

**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](/en/guides/data-controls).

## 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](/en/guides/tool-controls) · [JSON validation example](/en/guides/json-mode)

## 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](/en/guides/gemini-builtins) 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](/en/guides/gemini-builtins).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.