> ## Documentation Index
> Fetch the complete documentation index at: https://developer.beeble.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

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

## Error Response Format

All errors follow this format:

```json theme={null}
{
    "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](https://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](/docs/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 |

<Warning>
  `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.
</Warning>

### 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 |