Skip to content

fix: surface HTTP status and raw body in API errors - #322

Merged
gregberge merged 2 commits into
mainfrom
improve-api-errors
Jun 23, 2026
Merged

gregberge merged 2 commits into
mainfrom
improve-api-errors

Conversation

@gregberge

Copy link
Copy Markdown
Member

Problem

A failed Argos build surfaced an APIError with no message:

❌ Error while creating the Argos build
APIError:
    at throwAPIError (.../@argos-ci/api-client/dist/index.mjs:84:8)
    at upload (.../@argos-ci/core/dist/index.mjs:1542:33)

Root cause

formatAPIError returned error.error. When the error response body is not the expected { error: "..." } JSON shape, error.error is undefined, so new APIError(undefined) produces an empty message.

This happens when the error response does not originate from the Argos API itself:

  • The API's own errorHandler always returns { error: message } with a non-empty message.
  • apiFetch already turns any 5xx into "Internal Server Error (status)".

So an empty message means a non-5xx (4xx) response from infrastructure in front of the API (proxy, load balancer, CDN, rate limiter) returning an empty body or an HTML/plain-text page — e.g. 413 Payload Too Large, 429, a WAF 403, etc. openapi-fetch then sets error to {} or a raw string, neither of which has .error.

Fix

Make the formatter robust so the failure is always debuggable:

  • formatAPIError(error, response?) keeps the structured { error, details } message when present, otherwise falls back to the HTTP status (e.g. HTTP 413 Payload Too Large) plus the raw body (truncated to 500 chars), and "Unknown API error" as a last resort.
  • throwAPIError(error, response?) now accepts the response and attaches status + raw data to the thrown APIError.
  • APIError carries status?: number and data?: unknown (and sets name = "APIError").
  • Threaded the response into every throwAPIError/formatAPIError call site (core + cli).

The original failure would now read e.g. APIError: HTTP 413 Payload Too Large instead of a blank message.

Tests

Added packages/api-client/src/index.test.ts covering structured errors, empty-body status fallback, non-JSON bodies, truncation, and the enriched APIError. All api-client tests pass; check-types is clean across api-client/core/cli.

🤖 Generated with Claude Code

When an error response did not match the expected `{ error }` JSON shape
(empty body, HTML error page, or plain text from a proxy/CDN/load balancer
in front of the API), `formatAPIError` returned `undefined`, producing an
`APIError` with an empty message that was impossible to debug.

Fall back to the HTTP status (e.g. `HTTP 413 Payload Too Large`) and the
raw body, and attach `status`/`data` to `APIError`. Thread the response
through all `throwAPIError`/`formatAPIError` call sites.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@vercel

vercel Bot commented Jun 23, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
argos-js-sdk-reference Ready Ready Preview, Comment Jun 23, 2026 7:58pm

Request Review

Format APIError constructor / formatAPIError, and avoid conditional
expect in the throwAPIError test.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@gregberge
gregberge merged commit a4186e0 into main Jun 23, 2026
68 checks passed
@gregberge
gregberge deleted the improve-api-errors branch June 23, 2026 20:32

This branch was successfully deployed

1 active deployment
Preview — b2f29b4c Deployed Jun 23, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants