Troubleshooting

Use this page when a request fails, a flow does not complete as expected, or an output cannot be downloaded.

Debug Information

When investigating an issue, collect the following details:

endpoint and method, for example POST /flows
response HTTP status
response body
request timestamp
flow_id, if one was created
template name
input type and MIME type

Authentication Issues

401 Unauthorized

Authentication errors usually mean the API key is missing, invalid, expired, revoked, or sent with the wrong header format.

Check that every request includes an Authorization header in this format:

Authorization: Bearer <your-api-key>

Common responses:

{
  "detail": "API Key could not be verified"
}

{
  "detail": "Not authenticated"
}

To resolve the issue:

Verify the key is active in your account.
Make sure the header starts with Bearer followed by a single space.
Remove extra quotes, whitespace, or line breaks around the token.
Send the same header on status, output, and control requests.

Request Validation Issues

400 Bad Request - Invalid Template

This can happen when the template value contains a typo or references a template that is not available.

Example response:

{
  "message": "Template does not exist.",
  "template": "invalid_template"
}

To resolve the issue:

Confirm the template name with List All Templates.
Check the expected input and parameter shape in Templates.
Use the template guide that matches your workflow.

400 Bad Request - Unsupported MIME Type

Each template only accepts specific input types. Image templates, for example, accept these MIME types:

image/png
image/jpg
image/tiff
image/webp

Example response:

{
  "message": "Input mime type 'text/plain' is not allowed. Only the following mime types are allowed for the template: image/png, image/jpg, image/tiff, image/webp",
  "flow_id": "6a0ec3dafa057af721b0aed7",
  "flow_state": "created"
}

To resolve the issue:

Confirm the selected template supports the file type.
Make sure the data URL uses one of the allowed MIME types, such as data:image/png;base64,<base64-image>.
Ensure the uploaded file content matches the declared MIME type.

Invalid Or Malformed Input Data

Malformed data URLs, invalid base64 data, or inputs that do not match the selected template can prevent a flow from starting or completing successfully.

For text prompt inputs, send plain text without a data URL prefix:

{
  "data": "A modern office chair with armrests"
}

For image inputs, use one of the API-supported image MIME types:

{
  "data": "data:image/png;base64,<base64-image>"
}

Supported image data URL prefixes:

data:image/png;base64,
data:image/jpg;base64,
data:image/tiff;base64,
data:image/webp;base64,

For GLB inputs, use the GLB MIME type:

{
  "data": "data:model/gltf-binary;base64,<base64-glb>"
}

To resolve the issue:

Match the input type to the selected template.
Verify the base64 payload is complete and not truncated.
Use the helpers in Template Helpers to build data URLs.

Input Too Large Or Too Complex

Large files or very complex source assets may fail during processing, even if the initial POST /flows request succeeds. The maximum input size the API can handle is 100 MB.

To resolve the issue:

Reduce the file size to 100 MB or less.
Simplify the source asset.
Retry with a smaller input to confirm whether size or complexity caused the failure.

Flow Execution Issues

Flow Stays In A Non-Terminal State

Flows can move through states such as created, starting, running, or aborting before reaching a terminal state.

Terminal states are:

completed
failed
aborted

To handle long-running flows:

Poll the flow status every 3 to 5 seconds.
Add a client-side timeout.
Stop polling once the state is completed, failed, or aborted.

Flow State Is `failed`

A failed flow usually means processing could not complete for the selected template and input.

Common causes:

invalid or low-quality input data
template and input mismatch
unsupported source content
processing error

To resolve the issue:

Validate the input data and MIME type.
Retry with a simpler prompt or cleaner source file.
Check the flow response for available error details.
Keep the flow_id for support investigation.

Flow State Is `aborted`

An aborted flow was stopped before completion.

To resolve the issue:

Confirm whether your application sent an abort action.
Create a new flow if you want to retry the generation.
Do not expect outputs from a flow that was aborted before output generation.

Output Retrieval Issues

Outputs Are Not Ready

Outputs should be requested only after a flow reaches completed.

Example response:

{
  "message": "Outputs are only available when the flow has completed, aborted, or failed.",
  "state": "created"
}

To resolve the issue:

Poll the flow status first.
Wait until the state is completed.
List outputs before fetching a specific asset.

404 Not Found

A 404 response usually means the flow or asset identifier does not exist, or the asset does not belong to the specified flow.

Common responses:

{
  "message": "Specified flow not found"
}

{
  "message": "Flow not found"
}

To resolve the issue:

Verify the flow_id.
Fetch the outputs list for that exact flow.
Use the asset_id returned by the outputs response.

Flow Control Issues

400 Bad Request - Invalid Action

Flow control endpoints only accept supported action values.

Example response:

{
  "message": "Invalid action",
  "state": "aborting"
}

To resolve the issue:

Use only supported actions, such as start or abort.
Check the current flow state before sending a control action.
Avoid sending repeated control actions after the flow reaches a terminal state.

Throughput And Quotas

The Flow API is bounded by your plan quotas and by processing time for each flow. See Plans & Policies for current quota and rate limit guidance.

For client reliability:

Avoid excessive concurrent polling.
Add backoff when retrying failed requests.
Treat terminal flow states as final and create a new flow for retries.