# Errors

Failed API calls should be visible and actionable. Flownally often sits inside a customer communication workflow, so silent failures can turn into stale contacts, missed follow-up, or delayed replies.

Error responses use documented HTTP status codes and the generated `ProblemDetails` schema where available.

## Response shape

When an endpoint documents `ProblemDetails`, treat it as the structured error body for that operation. Exact fields are generated from the OpenAPI schema, but clients should be ready for:

- a short machine-readable problem type or code,
- a human-readable title or detail,
- field-level validation information when the request body is invalid,
- request metadata that support teams can use to investigate.

Do not parse error prose as business logic. Use the HTTP status code and documented schema fields.

## Common statuses

`400` means the request is malformed. Fix the request before retrying.

`401` means the bearer token is missing, malformed, expired, or revoked.

`403` means the credential is valid but does not have access to the tenant, object, or action.

`404` means the resource does not exist or is not visible to the credential.

`409` means the operation conflicts with the current state, such as trying to create a duplicate or modify something that has changed.

`422` means validation failed. Show the field-level problem to an operator or fix the integration payload.

`429` means the client is sending too many requests. Back off before retrying.

`5xx` means the request reached Flownally but the service could not complete it.

## Retries

Retry transient network failures and rate-limited requests with backoff. Do not retry validation errors without changing the request.

Recommended retry behavior:

- Retry network failures, `429`, and `5xx` responses with exponential backoff and jitter.
- Do not retry `400`, `401`, `403`, `404`, or `422` without changing credentials, permissions, object IDs, or payload data.
- Keep retries bounded so a failed sync does not create a backlog that slows down future work.
- Log the method, path, status code, and correlation metadata, but never log bearer tokens or customer message content unless your privacy policy allows it.

For workflows that affect conversations or follow-up, surface repeated failures to an operator. A broken automation should be visible before customers notice delayed replies.