e2b-dev / e2b-dev/runtime

Revisit structured errorCode for sandbox lifecycle API errors

Open
#3,180 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
1.6k
Forks
438
PR merge metrics
No merged PRs in 30d

Description

There was a previous closed PR for the base mechanism:
https://github.com/e2b-dev/infra/pull/2457

It added optional structured errorCode support to API errors, but it was closed without merge and current main does not appear to include it. I would like to check whether this direction is still acceptable, especially for sandbox lifecycle errors.

Today, different sandbox lifecycle failures can collapse into the same HTTP status and human-readable message. For example:

{
  "code": 500,
  "message": "Error killing sandbox: sandbox operation failed"
}

For clients, message is hard to use safely. It is intended for humans and can change with wording, wrapping, or lower-level error formatting. But clients need a stable way to decide whether an error is retryable.

Some sandbox errors should not be retried, while others may be transient:

  • sandbox_abnormally_exited: sandbox exited unexpectedly; retrying kill is not useful because the sandbox process is already gone
  • sandbox_state_conflict: delayed retry may be appropriate
  • sandbox_node_unavailable: bounded retry may be appropriate
  • sandbox_delete_rpc_failed: final state is unknown, retry briefly then escalate

Could E2B API errors expose an optional machine-readable errorCode, following the direction of #2457? It would not need to be present on every error response; handlers could omit it until a stable semantic code exists.

Example:

{
  "code": 500,
  "errorCode": "sandbox_abnormally_exited",
  "message": "Error killing sandbox: sandbox operation failed"
}

This would keep code and message backward compatible, while allowing SDKs and clients to avoid parsing human-readable messages.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing closed PR #2457 and the current sandbox lifecycle error handlers to compare the proposed base mechanism with main. Trace how lifecycle failures become HTTP responses, then determine which errors have stable retry semantics and what compatibility checks or tests would be needed for an optional errorCode design.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.