API Error Responses and HTTP Status Codes Reference

FormBharo returns structured JSON error bodies on every non-2xx response. There are four distinct error shapes, and knowing which one to expect for a given scenario makes error handling straightforward.

Error body shapes

Authentication failure

Returned by the authentication layer before the request reaches any endpoint logic. This shape always means the API key is missing, malformed, or invalid.

{
  "detail": "Invalid API key"
}

string

A short human-readable description of the authentication problem.

Paired with HTTP 401.

Endpoint error

Returned when an operation fails for a business-logic reason — for example, when you reference an agent or conversation that does not exist.

{
  "error": "Agent not found"
}

string

A short human-readable description of why the operation failed.

Paired with HTTP 404 (not found), 403 (forbidden), or 400 (bad request) depending on the nature of the failure.

Refused save (validation issues)

Returned when agent creation or update fails because the request body contains invalid configuration. See Agent Configuration and Branching for the fields that can trigger this response.

{
  "validation_issues": [
    {
      "field": "scripts.outro_incomplete",
      "message": "outro_incomplete requires outro to also be set"
    },
    {
      "field": "questions[2].branch_id",
      "message": "Unknown branch_id: fever-details"
    }
  ]
}

array

A list of all validation failures found in the request. The save is atomic — fix every issue and resubmit.

Show Fields in each validation_issues entry

string

The path to the field that failed — e.g., "questions[2].branch_id".

string

A human-readable explanation of the problem.

Paired with HTTP 400.

Refused answer edit (validation failure on PATCH)

Returned when PATCH /api/v1/agents/{agent_id}/conversations/{conversation_id}/form_data fails because one or more submitted values do not pass the question’s validation rules. See Validation for the full rule reference.

{
  "error": "Validation failed",
  "invalid_fields": {
    "phone": {
      "value": "999",
      "normalized_value": "999",
      "error": "Must be 10 digits",
      "source": "phone_number"
    }
  }
}

string

Always "Validation failed" for this shape.

object

A map of field names to failure details. Nothing is saved if this object is non-empty — fix all fields and resubmit.

Show Fields in each invalid_fields entry

any

The raw value you submitted.

any

The value after pre-processing (e.g., prefix stripping). This is what the rule actually tested.

string

A human-readable explanation of why the value was rejected.

string

The validation rule type that rejected the value — e.g., "phone_number" or "regex".

Paired with HTTP 400.

HTTP status codes

Code	Meaning
`400`	The request body or a query parameter is wrong. Check the error body for details — it will be either the endpoint error shape or one of the refused-save shapes.
`401`	No API key was provided, the key is malformed, or the key has been revoked. The response body uses the authentication failure shape with a `detail` field.
`403`	The API key is valid but not authorised for this action — for example, a non-admin key trying to manage other keys, or a key trying to access a workspace it does not belong to.
`404`	The resource does not exist, or it exists but is not visible to this API key. FormBharo does not distinguish between “does not exist” and “exists but forbidden” at the 404 level.
`422`	The request body did not match the expected field schema — a required field is missing, a field has the wrong type, or an unknown field was passed where none are accepted. The `detail` field is a list of objects, each with `type`, `loc`, `msg`, and `input` describing the mismatch.
`500`	A server-side read or write failure. Retry with exponential back-off. If the error persists, contact support with the request ID from the response headers if available.

Get Started

Core Concepts

Guides

Reference

API Error Responses and HTTP Status Codes Reference

Error body shapes

HTTP status codes

​Error body shapes

​HTTP status codes

Error body shapes

HTTP status codes