fix(api): canonical nested error envelope across the API (contract drift)#194
Merged
Conversation
The Go API returned several incompatible error shapes — flat
{"error":"msg","code":"X"}, bare strings, {"error":{...}} without a
code, and plain-text http.Error bodies — none matching the OpenAPI
ErrorResponse schema ({"error":{"code","message"}}). Both the TS and
Python SDKs parse the nested envelope, so every real API error was
mis-parsed by the SDKs and fell back to code=INTERNAL with the raw body
as the message.
Route all error responses through httputil.WriteError, which now emits
the nested {"error":{"code","message"}} shape, and add an UNAVAILABLE
code for 503s. Converts stats, status, stream, batch, auth, and
ratelimit; updates the tests that asserted the old shapes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of the hardening sweep (item C: cross-language contract drift).
The Go API emitted several incompatible error shapes — flat
{"error":"msg","code":"X"}, bare strings,{"error":{...}}without a code, top-levelinvalid_ids, and plain-texthttp.Errorbodies — none matching the OpenAPIErrorResponseschema ({"error":{"code","message"}}).Both the TypeScript (
parseApiError) and Python SDKs parse the nested envelope, so every real API error was mis-parsed and fell back tocode=INTERNALwith the raw JSON as the message.Fix: route all error responses through
httputil.WriteError, which now emits the canonical nested{"error":{"code","message"}}shape (matching OpenAPI + both SDKs); add anUNAVAILABLEcode for 503s. Converts stats, status, stream, batch, auth, and ratelimit; updates the tests that were asserting the old (wrong) shapes.Verified locally:
go build,go vet,go test ./...all green.Note (not changed): OpenAPI's optional
error.request_idvs the SDKs' optionalerror.fieldremain differently named; neither is emitted by the API today so it is latent only.