Resources
Errors
Error codes and error response format
The Beeble API uses conventional HTTP status codes and returns structured error responses with machine-readable error codes.
Documentation Index
Fetch the complete documentation index at: /docs/llms.txt
Use this file to discover all available pages before exploring further.
Error codes and error response 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 |
| 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 |
| Code | Description |
|---|---|
INVALID_API_KEY | API key is missing or invalid |
| 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) |
| Code | Description |
|---|---|
JOB_NOT_FOUND | Job doesn’t exist or is not owned by you |
| 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.| 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 |