> ## Documentation Index
> Fetch the complete documentation index at: https://docs.floral.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Handle Floral's stable API error envelope, error codes, and request IDs.

Public API failures use one JSON envelope:

```json theme={null}
{
  "error": {
    "code": "INVALID_INPUT",
    "message": "The request contains invalid values.",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

Branch on `error.code`, not the human-readable message. Include `requestId` when contacting Floral support.

| Code                    | Meaning                                                                                                                             |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `UNAUTHENTICATED`       | The bearer credential is missing or invalid.                                                                                        |
| `FORBIDDEN`             | The caller does not have the required scope or access.                                                                              |
| `NOT_FOUND`             | The resource is unavailable to this caller.                                                                                         |
| `FEATURE_DISABLED`      | The required Floral feature is disabled.                                                                                            |
| `INVALID_INPUT`         | A path, query, or request body failed validation.                                                                                   |
| `CONFLICT`              | The requested transition conflicts with current state.                                                                              |
| `INVALID_STATE`         | The resource is not in a state that permits this action. Reload it before deciding whether to retry.                                |
| `IDEMPOTENCY_CONFLICT`  | Within one operation, the idempotency key was already used with different canonical input. Use a new key for a new logical request. |
| `PRECONDITION_REQUIRED` | The operation requires an `If-Match` header.                                                                                        |
| `VERSION_CONFLICT`      | The supplied `ETag` is stale. Reload and reconcile before retrying.                                                                 |
| `RATE_LIMITED`          | The caller exceeded a current request limit. Respect `Retry-After`.                                                                 |
| `INTERNAL_ERROR`        | Floral could not complete the request. Retry with backoff when safe.                                                                |

## Request IDs

You may send an `X-Request-ID` header of up to 128 characters using letters, digits, `.`, `_`, `:`, `/`, and `-`. Floral echoes a valid ID in the response header and error envelope; invalid values are replaced with a generated ID. Generate a unique value per logical request and retain it in your integration logs.

## Safe retries

* Retry `429` and transient `5xx` responses with exponential backoff and jitter.
* Retry reads when the operation remains useful to your caller.
* Retry a write automatically only when it requires `Idempotency-Key`, and reuse the exact key, method, path, and body.
* Do not retry `412 VERSION_CONFLICT` until you reload and reconcile the current resource.

See [Reliability and retries](/developers/api/reliability) for rate-limit classes, idempotent replay, optimistic concurrency, and audit logging.