Error classes
| Class | When thrown | Key properties |
|---|---|---|
BabySeaError | API returns non-2xx | status, code, type, message, retryable, requestId, rateLimit, body |
BabySeaTimeoutError | Request exceeds timeout | message |
BabySeaRetryError | All retry attempts exhausted | lastError, attempts |
Catching errors
TypeScript
Error codes
| Code | Type | HTTP | Description |
|---|---|---|---|
BSE1001 | authentication_failed | 401 | Invalid or missing API key |
BSE1002 | key_expired | 401 | API key has expired |
BSE1003 | key_revoked | 401 | API key has been revoked |
BSE1004 | insufficient_credits | 402 | Not enough credits for this generation |
BSE1005 | rate_limit_exceeded | 429 | Too many requests, check rateLimit.retryAfter |
BSE1006 | ip_rate_limit_exceeded | 429 | IP-level rate limit (pre-auth) |
BSE1007 | ip_not_allowed | 403 | IP not in key’s allowlist |
BSE2001 | validation_error | 400 | Invalid request parameters |
BSE2002 | model_not_found | 404 | Unknown model identifier |
BSE2010 | payload_too_large | 413 | Request body exceeds 100 KB |
BSE3001 | provider_error | 502 | Provider returned an error |
BSE3002 | provider_timeout | 504 | Provider did not respond in time |
BSE3003 | all_providers_failed | 502 | All providers failed, failover exhausted |
BSE4001 | generation_not_found | 404 | Generation 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-Afterheader 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
Rate limit headers
Rate limit headers are included on every response:| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests per window |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait (only on 429 responses) |