Errors - Beeble API Documentation

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:

{
  "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.

{
  "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 before retrying a submission. Model-specific limits and required fields come from the selected model’s input_schema.