Skip to main content

Error classes

ClassWhen thrownKey properties
BabySeaErrorAPI returns non-2xxstatus, code, type, message, retryable, requestId, rateLimit, body
BabySeaTimeoutErrorRequest exceeds timeoutmessage
BabySeaRetryErrorAll retry attempts exhaustedlastError, attempts

Catching errors

TypeScript
import { BabySea, BabySeaError, BabySeaTimeoutError } from 'babysea-sdk';

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

try {
  await client.generate('google/nano-banana', {
    generation_prompt: 'A cute 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); // 'replicate'
        console.log(pe.code);
        console.log(pe.message);
      }
    }
  }

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

Error codes

CodeTypeHTTPDescription
BSE1001authentication_failed401Invalid or missing API key
BSE1002key_expired401API key has expired
BSE1003key_revoked401API key has been revoked
BSE1004insufficient_credits402Not enough credits for this generation
BSE1005rate_limit_exceeded429Too many requests, check rateLimit.retryAfter
BSE1006ip_rate_limit_exceeded429IP-level rate limit (pre-auth)
BSE1007ip_not_allowed403IP not in key’s allowlist
BSE2001validation_error400Invalid request parameters
BSE2002model_not_found404Unknown model identifier
BSE2010payload_too_large413Request body exceeds 100 KB
BSE3001provider_error502Provider returned an error
BSE3002provider_timeout504Provider did not respond in time
BSE3003all_providers_failed502All providers failed, failover exhausted
BSE4001generation_not_found404Generation ID not found

Auto-retry behavior

The SDK automatically retries retryable errors (429 rate limits, 5xx server errors):
  • Default: 2 retries (3 total attempts)
  • Respects Retry-After header from 429 responses
  • Falls back to exponential backoff: 1s → 2s → 4s → … (capped at 30s)
  • Non-retryable errors (400, 401, 402, 403, 404) throw immediately
TypeScript
// 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

Rate limit headers are included on every response:
HeaderDescription
X-RateLimit-LimitMaximum requests per window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the window resets
Retry-AfterSeconds to wait (only on 429 responses)