Errors

Img2Vid API errors use a consistent response format.

Error format

{
  "error": {
    "code": "invalid_api_key",
    "message": "Invalid or inactive API key.",
    "details": {}
  }
}

details is included only when additional structured information is available.

Authentication errors

Code	HTTP	Meaning	Recovery
missing_api_key	401	No API key was provided.	Send Authorization: Bearer <key>.
invalid_api_key	401	API key is invalid, inactive, or deleted.	Check or rotate the key.
invalid_api_key_owner	401	The key owner no longer exists.	Create a new key from an active account.

Request errors

Code	HTTP	Meaning	Recovery
invalid_request_body	400	JSON body is invalid or does not match the schema.	Validate request body fields and types.
unsupported_field	400	Nested or internal fields were sent.	Remove input, options, scene, sub_mode_id, provider, media type, and internal media fields.
missing_file	400	Multipart upload has no file field.	Add the file form field.

Model and mode errors

Code	HTTP	Meaning	Recovery
model_not_found	404	Model is unavailable.	Use a model key from /api/v1/media_models.
model_not_api_configured	422	Model has no public API configuration.	Pick another API-ready model.
mode_not_supported	422	Mode does not exist on the selected model.	Use operations[].mode from /api/v1/media_models.
mode_not_api_configured	422	Mode exists but has no public endpoint.	Use another listed operation.
unsupported_input_for_model	422	Input shape is unsupported.	Check the model mode input requirements.
ambiguous_generation_mode	422	Input matches multiple modes.	Pass mode explicitly.
mode_scene_missing	422	Mode is missing internal scene mapping.	Contact support; this is a configuration issue.

File errors

Code	HTTP	Meaning	Recovery
unsupported_file_type	415	MIME type is not image, video, or audio.	Upload a supported media file.
unsupported_file_format	415	File format is not allowed for the selected mode.	Check the model reference for allowed formats.
file_too_large	413	File exceeds the size limit.	Compress the file or choose a mode with a larger limit.
upload_failed	502	Storage provider upload failed.	Retry or contact support if persistent.
unsupported_upload_target	422	Configured upload target is unsupported.	Contact support; this is a configuration issue.

SDK error handling

SDKs expose non-2xx API responses as language-native exceptions or error values. Polling helpers can also surface timeout, failed-generation, and canceled-generation errors.

The snippets below assume you have already initialized the SDK client as shown in the Quickstart and imported the required language SDK types.

JavaScript / TypeScript

import { BubleAPIError } from '@buble/sdk';

try {
  await buble.generations.retrieve('task_id');
} catch (error) {
  if (error instanceof BubleAPIError) {
    console.error(error.status, error.code, error.message, error.details);
  }
}

Python

from buble_ai import BubleAPIError

try:
    client.generations.retrieve("task_id")
except BubleAPIError as error:
    print(error.status_code, error.code, error.message, error.details)

Go

_, err := client.Generations.Retrieve(ctx, "task_id")
if err != nil {
	var apiErr *buble.APIError
	if errors.As(err, &apiErr) {
		fmt.Println(apiErr.StatusCode, apiErr.Code, apiErr.Message, apiErr.Details)
	}
}

Rust

match client.generations().retrieve("task_id").await {
    Err(buble::Error::Api(error)) => {
        eprintln!("{} {:?} {}", error.status, error.code, error.message);
    }
    other => {
        // Handle success or other SDK error variants.
    }
}

Swift

do {
    _ = try await client.generations.retrieve("task_id")
} catch BubleError.api(let error) {
    print(error.statusCode)
    print(error.code ?? "")
    print(error.message)
}

Dart / Flutter

try {
  await client.generations.retrieve('task_id');
} on BubleApiException catch (error) {
  print(error.statusCode);
  print(error.code);
  print(error.message);
}

Elixir

case Buble.Generations.retrieve(client, "task_id") do
  {:ok, task} ->
    task

  {:error, %Buble.Error{type: :api, status: status, message: message}} ->
    IO.puts("Buble API error #{status}: #{message}")
end

Java

try {
    client.generations().retrieve("task_id");
} catch (BubleApiException error) {
    System.err.println(error.getStatusCode());
    System.err.println(error.getCode());
    System.err.println(error.getMessage());
    System.err.println(error.getDetails());
}

.NET

try
{
    await client.Generations.RetrieveAsync("task_id");
}
catch (BubleApiException error)
{
    Console.Error.WriteLine(error.StatusCode);
    Console.Error.WriteLine(error.Code);
    Console.Error.WriteLine(error.Message);
    Console.Error.WriteLine(error.Details);
}

PHP

use Buble\Exception\ApiException;

try {
    $client->generations()->retrieve('task_id');
} catch (ApiException $error) {
    echo $error->statusCode . PHP_EOL;
    echo $error->apiCode . PHP_EOL;
    echo $error->getMessage() . PHP_EOL;
    print_r($error->details);
}

Ruby

begin
  client.generations.retrieve("task_id")
rescue Buble::APIError => error
  warn error.status
  warn error.code
  warn error.message
  warn error.details
end