Banata

Platform

Errors & Retries

Handle Banata errors clearly, separate transient failures from product-state failures, and choose retry strategies that fit async sandbox workflows.

Good integrations separate:

  • permanent failures
  • temporary failures
  • plan or quota failures

If you do not separate those clearly, your retry logic will create noise and cost instead of resilience.

SDK error handling

Use BanataError when you want structured error handling.

ts
import { BanataSandbox, BanataError } from "@banata-boxes/sdk";
 
try {
  await client.launch();
} catch (error) {
  if (error instanceof BanataError) {
    console.error(error.status, error.code, error.message);
  }
}

Common categories

Auth errors

Examples:

  • invalid key
  • missing key

These usually should not be retried until credentials are fixed.

Quota or plan errors

Examples:

  • concurrency limit reached
  • monthly sandbox-hour limit reached
  • a feature is not available on the current plan

These are product-state issues, not transient infrastructure failures.

Temporary platform errors

Examples:

  • 500
  • 503
  • temporary timeouts

These are good candidates for retry with backoff.

Long-job timing issues

If a task is meaningful or may take a long time:

  • do not design around one synchronous response
  • use promptAsync()
  • track the task with taskId
  • use a webhook for completion

That is usually a better fix than simply increasing timeouts.

Retry advice

Retry:

  • temporary create failures
  • read operations
  • task state reads
  • other clearly transient errors

Avoid blind retry loops for:

  • invalid input
  • bad permissions
  • plan limit errors

Related pages