Skip to main content
FlownallyAPI Docs

Errors

LLM
View as Markdown
Open llms.txt

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.