Retry permanently-failed enrichments for a tenant
const url = 'http://localhost:8080/v1/tenants/example/enrichments/retry';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"enrichments":["translation"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:8080/v1/tenants/example/enrichments/retry \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "enrichments": [ "translation" ] }'Clears the terminal failure markers for a tenant so the reconciler will attempt those records again.
The automatic sweep deliberately never revives a terminal record: a terminal failure is a property of the record’s own text — a content-policy block, a refusal, an input past the model’s limit — so re-running it costs a provider call and fails identically. This endpoint is the override for when that premise has changed: the text was edited, or the provider changed its policy.
Because of that, it is rate limited per (tenant, enrichment). Clearing is a request to
spend a provider call on every record already known to fail, so an unbounded clear would be
a cost-amplification loop. A refused call returns cooling_down with the remaining wait
rather than silently doing nothing.
Every requested enrichment gets its own outcome — a tenant can have one cleared, one cooling down and one switched off in the same call. Responds 202: clearing is synchronous, but the retrying is not.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The tenant whose terminal failures should be cleared.
Request Body
Section titled “Request Body”Omit the body, or send an empty object, to clear every enrichment.
object
Which enrichments to clear. Omit or leave empty for all of them, which is the usual call. An unknown name is rejected rather than ignored, so a typo cannot come back as a successful no-op. A list longer than the three names is rejected too.
Responses
Section titled “Responses”Accepted; see each enrichment’s outcome.
object
object
cleared — the markers were removed and the records will be picked up by the next
reconcile sweep. cooling_down — this enrichment was cleared too recently; see
retry_after_seconds. disabled — the enrichment is not running for this tenant,
so clearing would queue work the worker skips; see disabled_reason.
How many records had a terminal marker removed. Zero with outcome cleared is a real
answer: nothing was permanently failed.
Present only for cooling_down. How long until this enrichment may be cleared again.
Present only for disabled. Same values the enrichment-status endpoint uses, so a
consumer needs one vocabulary rather than two.
Example
{ "results": [ { "enrichment": "translation", "outcome": "cleared", "disabled_reason": "not_configured" } ]}Bad Request. Returned for an unknown enrichment name, a body that is not a JSON object, an unknown or repeated member, malformed JSON, or a missing tenant id.
RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.
object
Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.
A human-readable explanation specific to this occurrence of the problem.
Optional structured context for this problem, e.g. resource_type on a 404.
object
A URI reference (typically the request path) identifying the specific occurrence of the problem.
Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.
A single invalid request parameter (RFC 9457 “invalid_params” extension member).
object
Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.
Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.
Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference identifying the problem type.
Example
{ "code": "validation", "detail": "One or more request parameters are invalid", "instance": "/v1/feedback-records", "invalid_params": [ { "name": "field_type", "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date" } ], "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b", "status": 400, "title": "Bad Request", "type": "https://hub.formbricks.com/problems/bad-request"}Unauthorized (missing or invalid API key)
RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.
object
Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.
A human-readable explanation specific to this occurrence of the problem.
Optional structured context for this problem, e.g. resource_type on a 404.
object
A URI reference (typically the request path) identifying the specific occurrence of the problem.
Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.
A single invalid request parameter (RFC 9457 “invalid_params” extension member).
object
Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.
Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.
Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference identifying the problem type.
Example
{ "code": "validation", "detail": "One or more request parameters are invalid", "instance": "/v1/feedback-records", "invalid_params": [ { "name": "field_type", "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date" } ], "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b", "status": 400, "title": "Bad Request", "type": "https://hub.formbricks.com/problems/bad-request"}Conflict. Returned when the reconciler is disabled on this deployment (clearing failures would have no effect until it is re-enabled), or when a tenant data purge currently holds the tenant’s write lock.
RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.
object
Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.
A human-readable explanation specific to this occurrence of the problem.
Optional structured context for this problem, e.g. resource_type on a 404.
object
A URI reference (typically the request path) identifying the specific occurrence of the problem.
Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.
A single invalid request parameter (RFC 9457 “invalid_params” extension member).
object
Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.
Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.
Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference identifying the problem type.
Example
{ "code": "validation", "detail": "One or more request parameters are invalid", "instance": "/v1/feedback-records", "invalid_params": [ { "name": "field_type", "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date" } ], "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b", "status": 400, "title": "Bad Request", "type": "https://hub.formbricks.com/problems/bad-request"}Request body exceeds the maximum allowed size.
RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.
object
Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.
A human-readable explanation specific to this occurrence of the problem.
Optional structured context for this problem, e.g. resource_type on a 404.
object
A URI reference (typically the request path) identifying the specific occurrence of the problem.
Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.
A single invalid request parameter (RFC 9457 “invalid_params” extension member).
object
Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.
Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.
Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference identifying the problem type.
Example
{ "code": "validation", "detail": "One or more request parameters are invalid", "instance": "/v1/feedback-records", "invalid_params": [ { "name": "field_type", "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date" } ], "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b", "status": 400, "title": "Bad Request", "type": "https://hub.formbricks.com/problems/bad-request"}default
Section titled “default”Error
RFC 9457 problem details (application/problem+json). Branch on the stable code member rather than on title or type.
object
Stable, machine-readable error code; the primary value to branch on. service_unavailable indicates a feature or dependency is temporarily unavailable and the request may be retried later. tenant_write_conflict indicates the write conflicted with an in-progress tenant data purge (or vice versa) and may be retried later unchanged. All other codes are terminal until the request itself is changed.
A human-readable explanation specific to this occurrence of the problem.
Optional structured context for this problem, e.g. resource_type on a 404.
object
A URI reference (typically the request path) identifying the specific occurrence of the problem.
Field-level validation failures (RFC 9457 “invalid_params” extension). Present on validation errors.
A single invalid request parameter (RFC 9457 “invalid_params” extension member).
object
Dotted path to the offending request field, e.g. ‘field_type’ or ‘items[0].field_type’.
Human- and agent-readable explanation of why the value is invalid, naming allowed values or constraints where applicable so the request can be corrected without guessing.
Identifier for this request, also returned in the X-Request-ID response header; include it when reporting a problem.
HTTP status code
A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
A URI reference identifying the problem type.
Example
{ "code": "validation", "detail": "One or more request parameters are invalid", "instance": "/v1/feedback-records", "invalid_params": [ { "name": "field_type", "reason": "must be one of: text, categorical, nps, csat, ces, rating, number, boolean, date" } ], "request_id": "0190a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b", "status": 400, "title": "Bad Request", "type": "https://hub.formbricks.com/problems/bad-request"}