## 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](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](https://developer.beeble.ai/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 |

`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