Errors

Every error is an RFC 9457 problem document with a stable machine-readable code; a failed operation is data, not an error.

The API has one error envelope. Whatever failed — validation, authentication, a pipeline precondition, the platform — the response is Content-Type: application/problem+json with the members of RFC 9457 plus two extensions:

{
  "type": "https://scenebrew.com/problems/missing-sdd",
  "title": "Conflict",
  "status": 409,
  "detail": "generate_scene_peg needs the scene's SDD; run generate_scene_sdd first",
  "instance": "/v1/scenes/0192a7c4-3f5e-7c8a-9b1d-2e3f4a5b6c7d/steps",
  "code": "missing_sdd"
}

Member	Meaning
`type`	A stable identifier derived from `code` (`https://scenebrew.com/problems/<code>`, kebab-case). `about:blank` when the status code is the whole story. Not a link — it is not dereferenced.
`title`	The HTTP status phrase.
`status`	The HTTP status code, repeated.
`detail`	Human-readable explanation of this occurrence. Wording may change; branch on `code`, not on `detail`.
`instance`	The request path.
`code`	Machine-readable error code, lower snake case. Absent when the status is self-explanatory.
`errors`	On `422` only: the field-level failures, each with `loc`, `msg`, `type`.

Successful responses never use this envelope; a 2xx body is the resource.

Status codes and codes

Status	`code`	When
`400`	`missing_brief`	`generate_scene_sdd` was requested without a `brief`.
`400`	`invalid_cursor`	A `cursor` that cannot be read, or one from another collection. See Pagination.
`400`	`invalid_prefer`	A `Prefer` header the API does not understand (`wait` above 60, an unknown token).
`400`	`no_files`, `kind_mismatch`	`POST /v1/files` without a part; a file whose content does not match the artifact or asset it is for.
`401`	—	No key, unknown key, or revoked key. `WWW-Authenticate: Bearer`.
`402`	`quota_exceeded_projects`	Your plan has no room for another project.
`403`	`insufficient_scope`	The key lacks the scope; the header names it. See Authentication.
`404`	—	No such resource in your workspace — also the answer for another workspace's ids.
`409`	`missing_sdd`	`generate_scene_peg` before the scene has a design.
`409`	`missing_peg`	`generate_scene_blueprint` before the scene has a graph.
`409`	`missing_blueprint`	`generate_scene_model` before the scene has a blueprint.
`409`	`step_in_progress`	A step was requested while another step runs on the scene.
`409`	`turn_in_progress`	A message was posted while the session's previous turn is still running.
`409`	`not_cancelable`	Cancel on an asset generation that has already started.
`409`	—	A scene name already used in the project.
`413`	`payload_too_large`	A file upload over 100 MB.
`415`	—	An upload whose media type is not GLB, PNG, JPEG or WebP.
`422`	—	The request did not match the schema; `errors` lists the fields.
`429`	—	Reserved for rate limits; not issued today.
`500`	—	Unexpected failure. Retry once; report it if it persists.
`501`	`not_implemented`	A step or generation kind that is declared on the contract but not available yet.
`502`	—	The platform behind the API is temporarily unavailable. Retry with backoff.

A 422 looks like this:

{
  "type": "about:blank",
  "title": "Unprocessable Content",
  "status": 422,
  "detail": "Request validation failed",
  "instance": "/v1/scenes/0192a7c4-3f5e-7c8a-9b1d-2e3f4a5b6c7d/steps",
  "errors": [
    {
      "type": "enum",
      "loc": ["body", "step"],
      "msg": "Input should be 'generate_scene_sdd', 'revise_scene_sdd', 'generate_scene_peg', …",
      "input": "make_sdd"
    }
  ]
}

Failures inside an operation

Work that was accepted (202) but did not finish is not an HTTP error: the operation ends with status: "failed" and an error object — code, message and retryable:

`error.code`	Meaning
`insufficient_credits`	The workspace has no credits for this step. Nothing was charged.
`sdd_issues`	The brief could not be turned into a consistent design. Rephrase and run `generate_scene_sdd` again.
`agent_unavailable`	The AI service could not be reached. Retry later.
`step_failed`	The step ran and failed; `message` carries the detail.
`layout_failed`, `brew_failed`	The procedural step failed on its input; `message` carries the detail.
`runner_unavailable`	The procedural runner could not be reached. Retry later.
`canceled`	You canceled it (`status` is `canceled`).
`generation_failed`, `generation_refused`, `generation_lost`	An asset generation failed, was refused by the generator, or was lost to a restart.

Credits are charged only when a step succeeds; a canceled turn pays for the model calls it had made.

Retrying

502, agent_unavailable, runner_unavailable and network errors: retry with exponential backoff.
Steps, session creates, messages and generations: send an Idempotency-Key so a retry after a lost response returns the operation already created instead of a second one.
The procedural steps are idempotent with respect to their inputs: rerunning them writes a new artifact version from the same graph or blueprint.

Status codes and codes

Failures inside an operation

Retrying

On this page