Preserving Structured Gemini Error Details in Vercel AI SDK

Engineering objective

System challenge

Gemini 429 responses can carry google.rpc.QuotaFailure and google.rpc.RetryInfo payloads, but the Google provider schema stripped error.details before the parsed response reached APICallError.data. Applications therefore lost provider-supplied retry timing unless they reparsed the raw response body.

Constraints

Working within real limits

• ✕Preserve arbitrary Google RPC detail payloads without over-modeling provider variants
• ✕Keep existing status, retryability, messages, headers, and successful responses unchanged
• ✕Prove the fix through the real failed-response handler rather than a schema-only assertion
• ✕Represent the transfer accurately: PR #18629 reported the fix; factory PR #18662 merged it

Architecture

System design

Approach

How it was built

1. 01

   Reproduced the detail loss through the existing Google failed-response handler.

2. 02

   Extended the schema with a nullish array of unknown detail payloads.

3. 03

   Added a representative Gemini 429 fixture containing QuotaFailure, RetryInfo, and retryDelay 34.4s.

4. 04

   Verified that both structured entries survive parsing into APICallError.data.

5. 05

   Kept the patch additive and isolated to the Google provider’s existing error path.

Workflow

Implementation flow

Technical validation

Implementation evidence

Observable engineering evidence. Discipline: MERGED UPSTREAM

Public evidence

Review the upstream contribution

Outcome

What was delivered

• Vercel factory PR #18662 merged the accepted fix upstream on August 11, 2026

• Vercel’s bugfix review marked the issue fully addressed with low side-effect and security risk

• The original reproduction no longer reproduced against the factory implementation

• Structured QuotaFailure and RetryInfo values now survive parsing without changing retry policy

Technologies

Stack and tools

Next engineering system