Product: Gemini API File Search (fileSearchStores, uploadToFileSearchStore, documents.get), v1beta, API key auth, paid tier.
Summary
A File Search document can report state STATE_FAILED from documents.get and later become STATE_ACTIVE with no client action. Clients that treat STATE_FAILED as terminal, which is how the docs present it, then delete or abandon documents that would have indexed successfully. Separately, when concurrent uploads go from 50 to 100 small docs, most documents go STATE_FAILED, while every upload call returns HTTP 200 and no 429 is ever returned.
Repro (2026-09-22, one project, europe-west1 client)
Step 1 - Create a store. Upload N plain-text documents concurrently via upload/v1beta/{store}:uploadToFileSearchStore (raw protocol, upload+finalize). Poll documents.get every 2s.
Step 2 - N = 10 / 25 / 50 x 100KB: every doc ACTIVE in 5-11s.
Step 3 - N = 100 x 100KB: 100 x HTTP 200, 84 docs report STATE_FAILED at first observation. A later documents.list shows 175 of 187 100KB docs in the store ACTIVE, so most “failed” docs recovered.
Step 4 - A single 1MB doc uploaded afterwards: STATE_FAILED, then STATE_ACTIVE at 110s after upload.
Step 5 - 5MB docs (30 concurrent, and 1 alone right after) remain STATE_FAILED.
Step 6 - Re-tested later the same day, single document at a time, ~2 min apart, no other concurrent load: 1MB reached ACTIVE at 18.3s; 5MB reached ACTIVE at 108.6s (no FAILED observed at all this time, contradicting Step 5 above); 20MB did not reach ACTIVE within a 5 minute poll ceiling, but no STATE_FAILED either, so true completion time is unknown and the client simply stopped waiting.
Questions
Q1 - Is STATE_FAILED meant to be terminal? If not, what is the recommended client behaviour (how long to keep polling), and can the API expose a failure reason or a distinct transient state?
Q2 - What throughput limit applies to File Search indexing (documents or tokens per minute per project or store)? No quota metric in Cloud Console shows it, and uploads never return 429.
Q3 - 5MB plain-text documents sometimes fail permanently (Step 5) and other times reach STATE_ACTIVE in under two minutes with no failure at all (Step 6), with no difference in our client code, only concurrency at time of upload seems to vary. Is 5MB near a real size or complexity threshold, or is this concurrency-related indexing contention? Is there a failure reason we can retrieve either way? Separately, a 20MB single document, well under the documented 100MB limit, had not reached ACTIVE after 5 minutes with no error. What is the expected indexing time for documents in the multi-MB range, and is there a recommended client poll or timeout budget?
Q4 - On 2026-08-28 around 16:40 UTC, every uploadToFileSearchStore call for a few minutes returned 429 RESOURCE_EXHAUSTED “Failed to count tokens.”, at single-user volume, a handful of docs. No project quota showed as exceeded. What limit does this 429 correspond to, and how can we monitor it?
Environment: plain HTTP client (Go net/http). Project quotas at their defaults (write_to_file_search_stores 3000/min; we used 233).