Skip to main content
The Beeble API uses conventional HTTP status codes and returns structured error responses with machine-readable error codes.

​
Error Response Format

All errors follow this format: 
{
    "error": {
        "message": "Human-readable error description",
        "code": "ERROR_CODE"
    }
}
FieldTypeDescription
messagestringHuman-readable description of the error
codestringMachine-readable error code

​
Error Codes

​
Validation Errors (400)

Returned when request parameters are invalid or missing.
CodeDescription
INVALID_GENERATION_TYPEgeneration_type must be "image" or "video"
INVALID_ALPHA_MODEalpha_mode must be "auto", "fill", "custom", or "select"
INVALID_MAX_RESOLUTIONmax_resolution must be 720 or 1080
MISSING_STYLE_INPUTNeither reference_image_uri nor prompt was provided
MISSING_SOURCEsource_uri is required
MISSING_ALPHAalpha_uri required when alpha_mode is "custom" or "select"
INVALID_FILE_FORMATSource format doesn’t match generation_type (e.g. video source for image generation)
ALPHA_TYPE_MISMATCHAlpha type doesn’t match source (image vs video) when alpha_mode is "custom"
ALPHA_MUST_BE_IMAGEAlpha must be an image (PNG/JPG) when alpha_mode is "select"
SOURCE_TOO_LARGESource resolution exceeds 2,770,000 total pixels (width × height)
VIDEO_TOO_MANY_FRAMESVideo exceeds the maximum of 240 frames
INVALID_URIURI format invalid or file type could not be determined
SOURCE_UNREACHABLESource, alpha, or reference URI is not reachable
INVALID_FILENAMEFilename invalid or unsupported extension
INVALID_CALLBACK_URLCallback URL is not valid HTTPS or is unreachable

​
Authentication Errors (401)

Returned when API key authentication fails.
CodeDescription
INVALID_API_KEYAPI key is missing or invalid

​
Billing Errors (402)

Returned when there is a billing or payment issue with your account.
CodeDescription
CREDIT_DEDUCTION_FAILEDNo billing account or no active API subscription

​
Not Found Errors (404)

Returned when the requested resource doesn’t exist.
CodeDescription
JOB_NOT_FOUNDJob doesn’t exist or is not owned by you

​
Rate Limiting (429)

Returned when you exceed the request rate limit.
CodeDescription
RATE_LIMIT_EXCEEDEDToo many requests

​
Server Errors (500)

Returned when an internal error occurs. These are not caused by your request.
CodeDescription
INTERNAL_ERRORUnexpected server error
CREDIT_DEDUCTION_FAILEDFailed to process credit deduction
UPLOAD_URL_FAILEDFailed to generate upload URL
JOB_QUEUE_FAILEDFailed to queue job for processing