The Beeble API uses conventional HTTP status codes and returns structured error responses with machine-readable error codes.
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 |
