Errors

Buble 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.

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.

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.

Code	HTTP	Meaning	Recovery
`model_not_found`	404	Model is unavailable.	Use a model key from `/api/v1/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/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.

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.