Errors

​

Error Response Format

{
  "status": "error",
  "request_id": "req_123456789",
  "error": {
    "code": "BSE2001",
    "type": "invalid_input",
    "message": "The request body contains invalid parameters.",
    "retryable": false,
    "details": {
      "field": "generation_prompt"
    }
  }
}

• code: A strict, non-changing alphanumeric code starting with BSE. Use this for programmatic error handling.
• type: A snake_case, human-readable categorization of the error.
• message: A detailed, human-readable message about what went wrong.
• retryable: A boolean indicating if the exact same request might succeed on a subsequent attempt.
• details: (Optional) Additional context related to the error.
• provider_errors: (Optional) Present when an upstream failover chain is exhausted, indicating each individual provider’s specific failure reason.

​

Schema Validation Rejections

​

Error Codes

​

Auto-retry behavior

• Default configuration: 2 retries (3 total execution attempts).
• Retryable errors: Rate limit saturation (BSE1005, BSE1006) and the majority of upstream provider transient failures (BSE4001, BSE4002, BSE4003, BSE4004, BSE4005, BSE4007, BSE4008, BSE4009).
• Non-retryable errors: Authentication, input validation, model configuration, and internal server faults are never retried.
• Backoff logic: Respects the Retry-After header on 429 responses, utilizing exponential backoff for other retryable classes.

​

Provider failover behavior

// Disable retries
const client = new BabySea({ apiKey: 'bye_...', region: 'us', maxRetries: 0 });

// More retries for batch jobs
const client = new BabySea({ apiKey: 'bye_...', region: 'us', maxRetries: 5 });

​

Rate limit headers

​

Troubleshooting common errors

​

”insufficient_credits” (BSE1004)

• Check your balance: await client.billing()
• Estimate cost first: await client.estimate(model, count)
• Purchase credits from Credit packs or upgrade your plan

​

”all_providers_failed” (BSE4003)

• The SDK executed retries automatically (verify your maxRetries configuration).
• Check provider status using client.health.providers() - see Provider health.
• Attempt routing through a different model or provider order.

​

”generation_not_found” (BSE2011)

• Verify the generation_id - it should be a UUID
• Make sure you’re using the correct API key
• Generations are deleted if they fail billing checks

​

Cancel conflicts and late completion

• The current public cancellation flow typically returns BSE2012 (generation_not_cancelable).
• Fast generations may finalize before the cancellation signal is processed.
• A successful generation remains charged even if the cancellation request arrived marginally too late.

• Treat cancellation as a best-effort signal for in-flight generations.
• Evaluate the generation status before retrying cancellation or deletion mutations.
• Utilize webhooks so your architecture can react instantaneously to completions.

​

”rate_limit_exceeded” (BSE1005)

• Wait for the window to reset (see X-RateLimit-Reset header)
• The SDK respects Retry-After and retries automatically by default
• Upgrade your plan for higher rate limits
• Batch requests efficiently to avoid unnecessary calls

​

Authentication failures

​

Implementation with the SDK

​

Error classes

​

Catching errors

import {
  BabySea,
  BabySeaError,
  BabySeaTimeoutError,
  BabySeaRetryError,
} from 'babysea';

const client = new BabySea({ apiKey: 'bye_...', region: 'us' });

try {
  await client.generate('google/nano-banana', {
    generation_prompt: 'A cute baby seal',
  });
} catch (err) {
  if (err instanceof BabySeaError) {
    console.log(err.status);     // 402
    console.log(err.code);       // 'BSE1004'
    console.log(err.type);       // 'insufficient_credits'
    console.log(err.message);    // human-readable description
    console.log(err.retryable);  // false
    console.log(err.requestId);  // request trace ID

    // Rate limit info (present on 429 responses)
    if (err.rateLimit) {
      console.log(err.rateLimit.limit);
      console.log(err.rateLimit.remaining);
      console.log(err.rateLimit.reset);
      console.log(err.rateLimit.retryAfter);
    }

    // Provider-level errors (when failover occurred)
    if (err.body.error.provider_errors) {
      for (const pe of err.body.error.provider_errors) {
        console.log(pe.provider); // provider identifier
        console.log(pe.code);
        console.log(pe.message);
      }
    }
  }

  if (err instanceof BabySeaTimeoutError) {
    console.log(err.message); // 'Request timed out after 30000ms'
  }

  if (err instanceof BabySeaRetryError) {
    console.log(err.attempts);              // total attempts made
    console.log(err.lastError.status);      // HTTP status of the last attempt
    console.log(err.lastError.code);        // BSE error code of the last attempt
  }
}