> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/api/platform/errors.md).

# Errors

Look up every FLORA API error code, what causes it, and how your code should recover, including run failures and when to retry.

FLORA returns conventional HTTP status codes and the same JSON error body on every non-2xx response. Branch on `error.code`, not on the message text, and log the `Flora-Request-Id` header so support can find the request.

## Error shape

```json
{
  "error": {
    "code": "input_validation_error",
    "message": "prompt: prompt is required.",
    "fields": [{ "field": "prompt", "message": "prompt is required." }]
  }
}
```

`fields` appears on two kinds of error: a validation error lists each rejected field, and a `revision_conflict` names the stale `base_revision`. Auth and not-found errors never carry `fields`.

Every response also includes a `Flora-Request-Id` header. Capture it:

```bash
curl -i https://app.flora.ai/api/v1/techniques/your-technique-slug/runs \
  -H "Authorization: Bearer $FLORA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": [], "mode": "async"}'

# HTTP/2 400
# flora-request-id: 0199c4b2-...
# content-type: application/json
#
# {"error":{"code":"input_validation_error","message":"..."}}
```

## Error codes

| HTTP | Code                                | Meaning                                                                                      | Retry?                       |
| ---- | ----------------------------------- | -------------------------------------------------------------------------------------------- | ---------------------------- |
| 400  | `invalid_json`                      | The body isn't valid JSON                                                                    | No, fix the request          |
| 400  | `input_validation_error`            | A field is missing, has the wrong type or ID prefix, or doesn't match the Technique's inputs | No, fix the request          |
| 401  | `unauthorized`                      | No `Authorization` header, an unrecognized key, or an expired OAuth session                  | No, fix the credential       |
| 401  | `invalid_api_key`                   | The key is unknown, revoked, or belongs to a deactivated account                             | No, fix the credential       |
| 402  | `insufficient_credits`              | The workspace balance can't cover the run                                                    | No, stop and tell the user   |
| 403  | `forbidden`                         | The key is valid but lacks permission for this workspace or action                           | No                           |
| 403  | `paid_plan_required`                | The workspace plan doesn't include this feature                                              | No                           |
| 404  | `not_found`                         | The ID, slug or route doesn't exist, or isn't visible to this key                            | No                           |
| 409  | `idempotency_duplicate`             | This `Idempotency-Key` was already accepted in the last two hours                            | No, look up the first result |
| 409  | `revision_conflict`                 | What you're writing changed since you read it                                                | After re-reading             |
| 429  | `rate_limited`                      | Too many requests for this workspace                                                         | Yes, with backoff            |
| 500  | `unknown_error` or `internal_error` | Something failed on FLORA's side                                                             | Yes, with backoff            |
| 503  | `temporarily_unavailable`           | A dependency is briefly unavailable                                                          | Yes, with backoff            |

### `400 invalid_json`

The request body wasn't valid JSON. With an SDK, this almost always points to a serialization bug in your code.

### `400 input_validation_error`

The body parsed, but a value is wrong. Read `fields` and `message`, then fix the payload. Common causes:

* An ID with the wrong prefix. Workspaces start with `ws_`, projects with `prj_`, Techniques with `tech_`, runs with `run_`.
* A generation `type` that isn't `image`, `video`, `audio`, `text` or `model3d`. Model families like `t2i` or `i2v` aren't types.
* A `model` that isn't an endpoint ID from `GET /models`.
* An asset `source` that isn't a string. Use `"signed-url"` or a public `https://` URL.
* Technique inputs that don't match the Technique. Call `GET /techniques/{slug}` and match every required input's `id` and `type`; unknown input IDs are rejected.
* A media input that isn't a public `https://` URL.
* Retrying a signed upload that already completed. Check it with `GET /assets/{assetId}` first. Completing the same upload twice is safe and returns the ready asset.

```ts
import { Flora, FloraError } from "@flora-ai/flora"

const errorCode = (err: FloraError) =>
  (err.body as { error?: { code?: string } } | undefined)?.error?.code

try {
  await client.techniques.runs.create({ techniqueId: "your-technique-slug", inputs: [], mode: "async" })
} catch (err) {
  if (err instanceof Flora.BadRequestError && errorCode(err) === "input_validation_error") {
    // Re-read the Technique's inputs and rebuild the payload
  }
}
```

### `401 unauthorized` and `401 invalid_api_key`

The request has no `Authorization: Bearer` header, or the key in it doesn't work. Check that the value has no stray whitespace, that `Bearer` isn't doubled, and that you read the right environment variable. If the key was revoked or its account deactivated, create a new key. See [Authentication](/api/platform/authentication.md).

Using FLORA MCP from an AI client? OAuth problems there are covered in [FLORA MCP troubleshooting](/mcp/troubleshooting.md).

### `402 insufficient_credits`

The workspace can't pay for the run. The message says what the run needs and what's available, and links to "About FLORA credits". Don't retry: the same request fails again until someone adds funds or changes plan. Stop, and show the message to the person who owns the workspace.

To avoid it, price work before you start it. A Technique's `run_cost` (`GET /techniques/{slug}`) and a model's `estimated_cost_usd` (`GET /models`) are in US dollars, and `POST /generate` with `quote: true` returns an `estimated_cost` without spending anything. See [How FLORA pricing works](/plans-and-billing/pricing.md).

### `403 forbidden`

The key is valid but can't do this. Common causes:

* The key has read but not write on the workspace, and you tried to create something or start a run.
* The workspace isn't one the key covers, or you were removed from it.
* A billing endpoint called without billing permission.

Check the key's workspaces and permissions in **Settings → API Keys**. If they look right, contact support with the `Flora-Request-Id`.

### `403 paid_plan_required`

The operation needs a feature the workspace's plan doesn't include, for example sharing a project for editing (`access: "edit"` on `POST /projects/{projectId}/share`). Use a variant the plan allows, such as sharing for viewing, or ask a workspace admin about the plan.

### `404 not_found`

The resource doesn't exist, or your key can't see it.

* Techniques: check the slug. `https://app.flora.ai/techniques/{slug}` is the source of truth.
* Runs: the run may belong to a different workspace, or the ID has a typo.
* Assets and projects: list the parent collection to confirm the ID.

### `409 idempotency_duplicate`

A mutating request with the same `Idempotency-Key` header was already accepted for this workspace and endpoint in the last two hours. The first request went through; don't send it again with a new key. Find its result instead, for example with `GET /generations` or `GET /technique-runs`. See [Idempotency](/api/platform/idempotency.md).

### `409 revision_conflict`

What you're writing changed since you read it, for example a canvas changeset whose `base_revision` is no longer current. Read the resource again and resend against its current revision. `fields` names the stale value as `<ref>.base_revision`, where `<ref>` is that operation's `ref` or `id` in your request.

### `429 rate_limited`

You've exceeded your workspace's request rate. Every request counts, including polls.

* Back off exponentially before retrying. If a `Retry-After` header is present, wait at least that many seconds.
* Reduce parallelism in batch jobs.
* Poll less often (about every 15 seconds per run), or use [webhooks](/api/platform/webhooks.md) instead of polling.
* Batch uploads with `POST /assets/reserve` and `POST /assets/complete`, which count once for up to 25 files.

### `500 unknown_error` and `500 internal_error`

Something broke on FLORA's side and the request didn't complete. Most unexpected failures report `unknown_error`; some report `internal_error`. Treat them the same. Retry with backoff. If it keeps happening, send the `Flora-Request-Id` to support.

### `503 temporarily_unavailable`

A service FLORA depends on is briefly unavailable. Retry with exponential backoff.

## Run failures

A run that starts can still fail while it executes. The create request succeeds, and the run's `status` later becomes `failed`, with an `error_code` and, when available, an `error_message`:

```json
{
  "run_id": "run_abc123",
  "status": "failed",
  "error_code": "GENERATION_PROMPT_MODERATED",
  "error_message": "..."
}
```

Common `error_code` values on generations:

| Code                                                       | Meaning                                                | What to do                                                            |
| ---------------------------------------------------------- | ------------------------------------------------------ | --------------------------------------------------------------------- |
| `GENERATION_PROMPT_MODERATED`                              | The model's safety filter rejected the prompt or input | Change the prompt or input                                            |
| `GENERATION_INPUT_VALIDATION`, `GENERATION_INVALID_PARAMS` | The model rejected an input or parameter               | Check the model's `params` in `GET /models`                           |
| `GENERATION_INVALID_URL`                                   | A media URL couldn't be used                           | Upload the file as an [asset](/api/guides/assets.md) and pass its URL |
| `GENERATION_PROVIDER_TIMEOUT`                              | The model didn't answer in time                        | Retry later, or try another model                                     |
| `GENERATION_FAILED_TO_START`, `GENERATION_GENERIC_ERROR`   | The run failed for another reason                      | Retry once; if it repeats, contact support                            |
| `BILLING_NOT_ENOUGH_CREDITS`                               | The workspace ran out of balance                       | Stop, as for `402 insufficient_credits`                               |

Technique runs can report other codes. Always show `error_message` when it's there. A failed run never retries on its own, and a new request is a new run that's billed again, so decide deliberately before you resubmit.

## Recovery patterns

### Retry transient errors

The TypeScript SDK already retries `408`, `429` and `5xx` responses twice, honoring `Retry-After`. If you call the API directly, or want more control, retry those statuses yourself:

```ts
import { FloraError } from "@flora-ai/flora"

async function withRetry<T>(fn: () => Promise<T>, max = 3): Promise<T> {
  let lastErr: unknown
  for (let attempt = 0; attempt < max; attempt++) {
    try {
      return await fn()
    } catch (err) {
      if (err instanceof FloraError && [429, 500, 503].includes(err.statusCode ?? 0)) {
        lastErr = err
        const retryAfter = Number(err.rawResponse?.headers.get("retry-after") ?? 0)
        const delay = Math.max(retryAfter * 1000, Math.min(1000 * 2 ** attempt, 30_000))
        await new Promise((resolve) => setTimeout(resolve, delay))
        continue
      }
      throw err
    }
  }
  throw lastErr
}
```

Retrying a request that starts a run can start it twice if the first attempt actually got through. Pair retries with [idempotency](/api/platform/idempotency.md).

### Don't retry caller errors

`400`, `401`, `402`, `403`, `404` and `409` mean the request itself needs to change. Sending it again gets the same answer, so log it or show it to the user instead.

## Contacting support

Email <support@florafauna.ai> with:

* The `Flora-Request-Id` response header, or the failing run's `run_id`
* The endpoint and HTTP method
* The error `code` and `message`
* The approximate time (UTC)
* Your workspace ID (`ws_...`)

Without a request ID, support usually can't find the request.

## Related

* [Authentication](/api/platform/authentication.md): 401s and key permissions.
* [Idempotency](/api/platform/idempotency.md): retry without duplicate runs.
* [Webhooks](/api/platform/webhooks.md): learn about failures without polling.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/api/platform/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
