Error Handling

Handle API errors gracefully in your application

Error Response Format

All error responses follow this structure:

{
  "statusCode": 402,
  "body": {
    "error": "Insufficient credits. Please buy more credits to continue."
  }
}

HTTP Status Codes

Status	Meaning	Description
200	Success	Request completed successfully
400	Bad Request	Invalid request body or parameters
401	Unauthorized	Missing or invalid API key
402	Payment Required	Insufficient credits
404	Not Found	Resource not found (e.g., uploaded image expired)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Something went wrong on our end

SDK Error Classes

Both SDKs provide typed error classes for precise error handling.

Python SDK

from bijou import (
    BijouClient,
    BijouAPIError,
    BijouInsufficientCreditsError,
    BijouRateLimitError,
    BijouValidationError,
    BijouTimeoutError,
)

client = BijouClient(api_key="bijou_your-key")

try:
    result = client.detect("image.jpg")
    print(f"Prediction: {result.prediction}")

except BijouInsufficientCreditsError as e:
    # User needs to buy more credits
    print(f"Out of credits: {e.message}")
    # Redirect user to billing page

except BijouRateLimitError as e:
    # Too many requests - wait and retry
    print(f"Rate limited. Retry after {e.retry_after} seconds")
    time.sleep(e.retry_after)

except BijouValidationError as e:
    # Invalid input (e.g., bad image format)
    print(f"Validation error on '{e.field}': {e.message}")

except BijouTimeoutError as e:
    # Request took too long
    print(f"Request timed out after {e.timeout_ms}ms")

except BijouAPIError as e:
    # Generic API error
    print(f"API error: {e.message} (HTTP {e.status_code})")
    if e.is_retryable:
        # Retry the request
        pass

TypeScript SDK

import {
  BijouClient,
  BijouAPIError,
  BijouInsufficientCreditsError,
  BijouRateLimitError,
  BijouValidationError,
  BijouTimeoutError,
} from '@bijou/sdk';

const client = new BijouClient({ apiKey: 'bijou_your-key' });

try {
  const result = await client.detect(imageBuffer);
  console.log(`Prediction: ${result.prediction}`);

} catch (error) {
  if (error instanceof BijouInsufficientCreditsError) {
    // User needs to buy more credits
    console.log(`Out of credits: ${error.message}`);

  } else if (error instanceof BijouRateLimitError) {
    // Too many requests - wait and retry
    console.log(`Rate limited. Retry after ${error.retryAfter} seconds`);
    await sleep(error.retryAfter * 1000);

  } else if (error instanceof BijouValidationError) {
    // Invalid input
    console.log(`Validation error on '${error.field}': ${error.message}`);

  } else if (error instanceof BijouTimeoutError) {
    // Request took too long
    console.log(`Timed out after ${error.timeoutMs}ms`);

  } else if (error instanceof BijouAPIError) {
    // Generic API error
    console.log(`API error: ${error.message} (HTTP ${error.statusCode})`);
    if (error.isRetryable) {
      // Retry the request
    }
  }
}

Error Reference

BijouInsufficientCreditsError

Thrown when the user’s credit balance is too low to complete the request.

Property	Type	Description
message	string	Error message from API
status_code	number	Always 402
code	string	"INSUFFICIENT_CREDITS"
request_id	string?	Request ID for debugging

Resolution: Purchase more credits at trybijou.com/profile.

BijouRateLimitError

Thrown when too many requests are made in a short period.

Property	Type	Description
message	string	Error message
retry_after	number	Seconds to wait before retrying
request_id	string?	Request ID for debugging

Resolution: Wait for retry_after seconds, then retry.

BijouValidationError

Thrown when the request contains invalid data.

Property	Type	Description
message	string	Validation error message
field	string?	Field that failed validation

Resolution: Fix the invalid input and retry.

BijouTimeoutError

Thrown when a request takes too long to complete.

Property	Type	Description
message	string	Timeout message
timeout_ms	number	Timeout duration in milliseconds

Resolution: Retry the request. If it persists, contact support.

BijouAPIError

Base class for all API errors. Catch this to handle any API error.

Property	Type	Description
message	string	Error message
status_code	number	HTTP status code
code	string	Error code
request_id	string?	Request ID for debugging
is_retryable	boolean	Whether the request can be retried

Retryable Errors

The SDK automatically retries these errors with exponential backoff:

• 5xx server errors
• 429 rate limit errors
• Network timeouts

Non-retryable errors (no automatic retry):

• 400 bad request
• 401 unauthorized
• 402 insufficient credits
• 404 not found