Errors - Floral Documentation

Public API failures use one JSON envelope:

{
  "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 for rate-limit classes, idempotent replay, optimistic concurrency, and audit logging.

⌘I