feat: add GatewayError for Blaxel gateway-synthesized errors

[devin-ai-integration]

Summary

Adds structured gateway error support to the TypeScript SDK. When the Blaxel gateway proxy synthesizes an error response (identified by the X-Blaxel-Source: platform header), the SDK now throws a GatewayError with typed properties:

• GatewayError class extending Error with errorCode, statusCode, retryable, action, doNot?, docsUrl?, and response properties
• 10 error code constants in errorCodes.ts (ERR_ROUTE_NOT_FOUND, ERR_WORKLOAD_UNAVAILABLE, etc.)
• gatewayErrorInterceptor response interceptor that detects X-Blaxel-Source: platform and throws GatewayError with parsed body fields — registered before the auth interceptor so gateway errors are caught first
• SandboxAction.handleResponseError() updated to check for gateway headers and throw GatewayError instead of ResponseError when appropriate
• All new symbols exported from @blaxel/core

Changes:

• @blaxel/core/src/client/gatewayError.ts — new GatewayError class
• @blaxel/core/src/client/errorCodes.ts — new file with 10 error code constants
• @blaxel/core/src/client/responseInterceptor.ts — new gatewayErrorInterceptor + registered in responseInterceptors array
• @blaxel/core/src/sandbox/action.ts — gateway error detection in handleResponseError()
• @blaxel/core/src/index.ts — re-export new symbols

Review & Testing Checklist for Human

• Verify the gatewayErrorInterceptor correctly clones the response before reading the body, so downstream interceptors still have access to the original
• Confirm the interceptor ordering (gateway before auth) doesn't interfere with 401/403 gateway errors — the gateway interceptor will throw before the auth interceptor runs, which is the desired behavior
• Test against a live gateway error (e.g. request to a non-existent workload) and confirm GatewayError is thrown with correct errorCode and retryable values

Notes

• The gatewayErrorInterceptor is registered in responseInterceptors[] before authenticationErrorInterceptor, so gateway-synthesized 401/403 errors will throw GatewayError (with the stable error code) instead of getting the auth doc link treatment — this is intentional since gateway errors have richer structured metadata
• SandboxAction.handleResponseError() also checks for gateway headers directly since sandbox subsystems may bypass the interceptor chain in some code paths (e.g. direct h2Fetch calls)

Link to Devin session: https://app.devin.ai/sessions/90f8d135f6e64ae8b771918c3ceeec6a
Requested by: @Joffref

---

Note

Adds a GatewayError class and supporting infrastructure to surface structured errors from the Blaxel gateway proxy. When a response carries X-Blaxel-Source: platform, the SDK now throws GatewayError with typed fields (errorCode, retryable, action, etc.) instead of a generic error. A new interceptor handles the common HTTP path; SandboxAction.handleResponseError() handles the direct-fetch path.

^{Written by Mendral for commit b663f9e.}

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[mendral-app]

LGTM

The P0 bug from the previous review — interceptor throwing on 2xx gateway responses — is fixed in b663f9e with the if (response.ok) return response; guard. The implementation is correct: the interceptor clones the response before reading the body, ordering is intentional, and the handleResponseError duplication correctly covers the direct-fetch path.

_{Tag @mendral-app with feedback or questions. View session}