Errors

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"
    }
}

Field	Type	Description
`message`	string	Human-readable description of the error
`code`	string	Machine-readable error code

Error Codes

Validation Errors (400)

Returned when request parameters are invalid or missing.

Code	Description
`INVALID_GENERATION_TYPE`	`generation_type` must be `"image"` or `"video"`
`INVALID_ALPHA_MODE`	`alpha_mode` must be `"auto"`, `"fill"`, `"custom"`, or `"select"`
`INVALID_MAX_RESOLUTION`	`max_resolution` must be `720` or `1080`
`MISSING_STYLE_INPUT`	Neither `reference_image_uri` nor `prompt` was provided
`MISSING_SOURCE`	`source_uri` is required
`MISSING_ALPHA`	`alpha_uri` required when `alpha_mode` is `"custom"` or `"select"`
`INVALID_FILE_FORMAT`	Source format doesn’t match `generation_type` (e.g. video source for image generation)
`ALPHA_TYPE_MISMATCH`	Alpha type doesn’t match source (image vs video) when `alpha_mode` is `"custom"`
`ALPHA_MUST_BE_IMAGE`	Alpha must be an image (PNG/JPG) when `alpha_mode` is `"select"`
`SOURCE_TOO_LARGE`	Source resolution exceeds 2,770,000 total pixels (width × height)
`VIDEO_TOO_MANY_FRAMES`	Video exceeds the maximum of 240 frames
`INVALID_URI`	URI format invalid or file type could not be determined
`SOURCE_UNREACHABLE`	Source, alpha, or reference URI is not reachable
`INVALID_FILENAME`	Filename invalid or unsupported extension
`INVALID_CALLBACK_URL`	Callback URL is not valid HTTPS or is unreachable

Authentication Errors (401)

Returned when API key authentication fails.

Code	Description
`INVALID_API_KEY`	API key is missing or invalid

Billing Errors (402)

Returned when there is a billing or payment issue with your account.

Code	Description
`BILLING_NOT_CONFIGURED`	No billing account or no active API subscription. Set up billing at developer.beeble.ai
`INSUFFICIENT_BALANCE`	Prepaid account balance is too low for this job. Top up your balance to continue
`HARD_LIMIT_EXCEEDED`	This job would push your current period usage over your spending limit. Wait for the next billing cycle or contact support to increase your limit
`CREDIT_DEDUCTION_FAILED`	Failed to process credit deduction (server-side issue)

Not Found Errors (404)

Returned when the requested resource doesn’t exist.

Code	Description
`JOB_NOT_FOUND`	Job doesn’t exist or is not owned by you

Rate Limiting (429)

Returned when you exceed a rate or concurrency limit. See Rate Limits for details.

Code	Description
`RATE_LIMIT_EXCEEDED`	Too many requests per minute. Back off and retry after a short delay
`CONCURRENT_LIMIT_EXCEEDED`	Too many in-flight generation jobs. Wait for running jobs to complete before submitting new ones

RATE_LIMIT_EXCEEDED and CONCURRENT_LIMIT_EXCEEDED require different retry strategies. For RPM limits, use exponential backoff. For concurrency limits, poll your active jobs and wait for one to finish.

Server Errors (500)

Returned when an internal error occurs. These are not caused by your request.

Code	Description
`INTERNAL_ERROR`	Unexpected server error
`CREDIT_DEDUCTION_FAILED`	Failed to process credit deduction
`UPLOAD_URL_FAILED`	Failed to generate upload URL
`JOB_QUEUE_FAILED`	Failed to queue job for processing

Get Started

Uploads

SwitchX

Account

Resources

Error Response Format

Error Codes

Validation Errors (400)

Authentication Errors (401)

Billing Errors (402)

Not Found Errors (404)

Rate Limiting (429)

Server Errors (500)

​Error Response Format

​Error Codes

​Validation Errors (400)

​Authentication Errors (401)

​Billing Errors (402)

​Not Found Errors (404)

​Rate Limiting (429)

​Server Errors (500)

Error Response Format

Error Codes

Validation Errors (400)

Authentication Errors (401)

Billing Errors (402)

Not Found Errors (404)

Rate Limiting (429)

Server Errors (500)