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

> ## Agent Instructions
> This site documents two API families. Choose the family before generating integration code and keep its request fields, billing, statuses, responses, and webhooks together.
> SwitchX API: POST /v1/switchx/generations; use /quickstart and /authentication. Completed generation files are under output.
> Enterprise API: POST /v1/products/{product}/jobs and GET /v1/product-jobs/{job_id}; use /enterprise/quickstart and /products. Check /enterprise for current access requirements. Completed product files are under outputs.
> For product jobs, fetch model-specific input_schema from GET /v1/products/{product}/models. OpenAPI defines the common job response; product guides show illustrative completed outputs. Do not treat output examples as exhaustive schemas.
> SwitchX 2.0 Finish uses the separate switchx_finish product and model_id switchx-2.0. Follow /products/switchx-finish: pass inputs.parent_job_id (a completed Standard switchx product generation's public dap_ ID owned by the same key owner, organization, and team) and inputs.target_resolution (1080 or 2160), without uploading media. Fast results, Finish results, and legacy SwitchX API generations cannot be parents. Estimate the transition, then submit and poll the new child ID; result files are under outputs.
> For product APIs, authenticate with an Organization API Key in x-api-key and keep the same organization and X-Beeble-Team-Id context for uploads, estimates, submissions, and reads. Use Beeble Cloud credits; product routes do not support USD.
> Follow /enterprise/llms-txt for the product API workflow: discover products and models, upload media, estimate credits, submit with an idempotency_key, and poll or receive webhooks. On an uncertain submission, retry the same body and key; do not create a replacement job.
> Product-job success is status=success; stop polling on failed, cancelled, or credit_required. Use the chosen product guide for completed response examples and download fields. Refer to /enterprise/errors, /enterprise/rate-limits, /guides/billing, and /guides/jobs for failures, limits, and refunds.

# 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

Some Developer API errors use this envelope:

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

Product routes can also return FastAPI-style `detail` responses. `detail` may
be a string, an object, or a validation-error array. Do not assume every error
has `error.code`.

```json theme={null}
{
  "detail": {
    "error_code": "INVALID_INPUT",
    "unknown_fields": ["source_uri"],
    "missing_fields": ["source"]
  }
}
```

### Product job errors

| Status or code             | What to do                                                                                                                                         |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `UNSUPPORTED_BILLING_UNIT` | Omit `billing_unit` or set it to `"credits"`; product estimates and jobs do not support USD.                                                       |
| `402` / `BUDGET_EXCEEDED`  | Check the Beeble Cloud credit balance, team budget, and your `max_credits` ceiling.                                                                |
| `403`                      | Check organization membership, key access, enabled product, team, and model consent.                                                               |
| `409`                      | Inspect the detail: a changed idempotent body or an unsupported organization policy can conflict. Do not blindly retry with a new idempotency key. |
| `422` / `INVALID_INPUT`    | Match `inputs` to the selected model’s `input_schema`.                                                                                             |
| `429`                      | Back off if an upstream service is rate-limited. Organization keys have no Beeble Developer API request or concurrency limit.                      |
| `5xx` or network timeout   | Preserve the exact request and idempotency key; the submission outcome may be uncertain.                                                           |

See [Jobs & retries](/docs/guides/jobs#safe-retries) before retrying a submission.

Model-specific limits and required fields come from the selected model’s `input_schema`.