sdk(ts,python): non-404 HTTP errors lose status + envelope detail
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 45/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- python, typescript
- Domain
- backend-api-design
Research direction
Read packages/sdk-typescript/src/client.ts and packages/sdk-python/src/mpak/client.py, then trace the non-2xx handling in the roughly six affected methods in each SDK. Compare how each SDK represents errors and how callers can inspect status and registry error codes. Done means both SDKs consistently preserve the registry envelope and HTTP status across those methods; the issue leaves error class design and versioning open.
Written by the indexing model from the issue text.
Description
Both the TypeScript and Python SDKs collapse most non-2xx registry responses into a generic MpakNetworkError, dropping the registry's structured error envelope on the floor. Net effect: callers can distinguish "not found" from "everything else," but cannot tell a 400 (bad input) apart from a 503 (registry down) without parsing the error message string.
Current behavior
TypeScript SDK — see packages/sdk-typescript/src/client.ts:
getServerDownload,getBundleDownload,getServer,getSkill, etc. all use the pattern:if (response.status === 404) throw new MpakNotFoundError(...); if (!response.ok) throw new MpakNetworkError(`HTTP ${response.status}`);- 400 (
BadRequestErrorfrom the registry — e.g. only one ofos/archsupplied), 401, 403, 500, 503 all classify the same. - The registry's error body
{ error: { message, code, statusCode } }is discarded.
Python SDK — see packages/sdk-python/src/mpak/client.py:
- Better, but inconsistent.
get_server_download,get_bundle_downloadraiseMpakError(f"HTTP {status}: {body}", "HTTP_ERROR", status)for non-404 errors viahttpx.HTTPStatusError. - Status code is preserved, but
codefrom the envelope is hardcoded to"HTTP_ERROR"regardless of the registry's actual code (VALIDATION_ERROR,RATE_LIMITED, etc.).
Why it matters
- Retry logic: callers can't safely retry only on 5xx without string-parsing the message.
- UX: a CLI that wraps the SDK can't distinguish "your
--platformflag is wrong" from "registry is having a bad day." - 400 path is reachable in practice on the new
/servers/.../downloadendpoint whenosxorarchis supplied — Fastify validates againstBundleDownloadParamsSchemaand the route'sresolveArtifactalso throwsBadRequestError. The TS SDK reports this asMpakNetworkError: HTTP 400, which reads like a transient network issue.
Proposed fix
Symmetric across both SDKs. Two viable paths:
- Add
MpakValidationError(4xx-class) andMpakServerError(5xx-class) to both SDKs' error hierarchies. Map ranges explicitly; keepMpakNotFoundErroras a sub-class ofMpakValidationError. - Parse the registry's envelope into a single
MpakError(message, code, status)everywhere.codecarries the registry'scodefield; callers pattern-match oncoderather than class. Closer to Python's existing shape.
Either way, every method's non-2xx branch wants the same translation function:
async function translateError(response: Response, context: string): Promise<never> {
const body = await response.json().catch(() => null);
const code = body?.error?.code ?? 'HTTP_ERROR';
const message = body?.error?.message ?? `HTTP ${response.status}`;
if (response.status === 404) throw new MpakNotFoundError(context);
if (response.status >= 400 && response.status < 500) {
throw new MpakValidationError(message, code, response.status);
}
throw new MpakServerError(message, code, response.status);
}
Scope
Affects ~6 methods in each SDK that go through fetchWithTimeout (TS) or self._client.get/post (Python). Worth doing as one PR per SDK rather than per-method.
Open questions
- Should
MpakValidationErrorcover 401/403 too, or split intoMpakAuthError? - Python's
MpakErroralready hascodeandstatus_code— keep the existing class and addMpakValidationError(MpakError)as a sub-class so existingexcept MpakErrorkeeps working? - Bump SDK majors on this, or treat as additive (new sub-classes don't break existing
except MpakNetworkErrorsince 5xx still raises a network-y error)?
Out of scope
This issue covers SDK error classification only. The registry already returns properly-structured error envelopes — no registry-side changes needed.
- Dominant language
- TypeScript
- Stars
- 14
- Forks
- 13
- Avg merge
- 16m
- Merged PRs (30d)
- 4
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from NimbleBrainInc/mpak
-
Difficulty 1/5 Under an hour Newbie friendliness 88/100
NimbleBrainInc/mpak#180 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
NimbleBrainInc/mpak#175 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 73/100
NimbleBrainInc/mpak#159 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
NimbleBrainInc/mpak#120 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 77/100
NimbleBrainInc/mpak#112 ·
All issues in NimbleBrainInc/mpak
Similar issues
-
bug documentation
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Potential Bug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
Comfy-Org/ComfyUI_frontend#23773 ·
Maintainers usually reply within 1 day
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Difficulty 1/5 Under an hour Newbie friendliness 85/100
lingdojo/kana-dojo#34301 · 1 comment · 5 reactions ·
Maintainers usually reply within 1 day
-
code-quality refactoring
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
github/gh-aw-firewall#11797 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
code-yeongyu/senpi#7007 ·
Maintainers usually reply within 1 day