Skip to main content
Automation API

Errors & broken reasons

Use these codes to handle Automation API errors and to find out why an automation is broken.

HTTP errors​

The Automation endpoints use the standard Tape error envelope. On this resource:

StatusWhen
400A malformed body, a path ID that isn't an integer, or a run body that doesn't match the automation's trigger. The two Advanced / sandbox endpoints also return 400 for a missing automation or record.
401The request carries no credential, or the credential doesn't act on behalf of a user where the endpoint needs one, for example an automation API key.
403A personal access token or OAuth access token lacks the capability the endpoint needs. The response carries WWW-Authenticate: Bearer error="insufficient_scope". See Capabilities.
404The automation, app, workspace, revision or record isn't available to you. See The 404 collapse. Manual run and simulate also return 404 when the target record is missing or you can't view it.
409A conflict with the automation's state: activating, running or simulating a broken automation.

What returns 400 in a definition body​

Besides a malformed envelope, the input schema of a definition rejects the following when you write it:

  • An action without a config key, or with a config that lacks a member its config_schema requires. An empty config: {} passes only for types without required members, for example current_record_update or collect_app_records. custom_code without code returns 400.
  • A malformed dynamic-value reference: an unknown source on a kind: "variable" reference, an unknown value_type on a kind: "value" reference, or a field reference without field_type.
  • An unknown enum value, for example an invalid assignment_type inside a field_assignments or call_arguments entry, or any config enum value that isn't one of the listed lower-case values.
  • A filter or actions tree nested deeper than the maximum block depth.
  • A malformed filter comparison, in the top-level filter or in a condition inside an action:
    • a value tagged for a channel the field doesn't have,
    • an empty comparison value,
    • a value-arity mismatch: a value on an operator with arity none such as is_empty, or a missing value on an operator that needs one.
  • An explicitly empty top-level filter group (rows: []). Send filter: null to run without a filter.
  • A malformed value union in a filter condition:
    • a payload key that belongs to a different channel than its type tag (each type branch accepts only its own keys),
    • a relative date value with an operator or unit outside the listed values,
    • a scalar amount (it must be a code-value array),
    • an unknown member.

Problems of meaning don't return 400 on write. Examples: a member that only validation requires, a referenced ID that doesn't exist, or an operator outside a field's channel. They show up as broken-reason codes when you validate or activate, and some only when the automation runs. One exception: an action app_id that never existed (not a deleted app) makes validate and activate return 404.

The 404 collapse​

Tape IDs are unique across all organizations, so existence and access collapse into a single 404. An automation that is missing, soft-deleted, in another organization (not 403), in a workspace you don't administer or outside your personal access token's content access returns the same 404. The API never reveals which IDs exist.

The broken state​

An automation's broken_reason is { errors: [...] } or null. It's also null when broken is true because Tape marked the automation broken during a run. GET /v1/automation/{id}/validate returns { valid, errors } with the same entry shape, computed fresh.

Each error entry:

PropertyTypeDescription
codestringMachine-readable reason. See Broken-reason codes.
messagestringEnglish description. Not translated.
deactivatedbooleantrue when the fault is inside a deactivated block, which doesn't break the automation. false on filter and action entries in an active block. Absent on trigger entries. Treat a missing value as false: test !entry.deactivated, not === false.
block_id / action_idstring | nullThe node at fault. action_id is null for a top-level fault, for example a filter or field assignment reason.
app_id / field_id / view_id / automation_id / user_id / record_id / option_idintegerThe referenced entity at fault, depending on code.
match_typestringPresent for filter_match_type_invalid: the invalid filter match type.
assignment_typestringPresent for field_assignment_type_invalid: the invalid field assignment type.
call_argumentstringPresent for action_call_argument_invalid: the ID of the invalid call argument.
Why can broken lag behind the current definition?

broken shows the last verdict Tape stored: create, update, activate and validate never write it, and a failed activate returns 409 with the object unchanged. Call validate for a current verdict. The automation object has the full broken model.

Broken-reason codes​

The codes use public names, never internal ones. Where shows where the fault sits. Description is the English message that Tape returns with the code.

CodeWhereDescription
trigger_variable_missingTriggerThe trigger references a variable that no longer exists.
trigger_app_missingTriggerThe trigger references an app that no longer exists.
trigger_date_field_not_dateTriggerThe date-arrived trigger references a calculation field that does not produce a date.
trigger_periodic_week_days_emptyTriggerThe weekly periodic trigger has no weekdays selected.
trigger_periodic_month_days_emptyTriggerThe monthly periodic trigger has no days selected.
trigger_updated_fields_emptyTriggerThe record-updated trigger has an empty list of watched fields.
filter_match_type_invalidFilterA filter condition uses an operator that is not valid in this context.
filter_variable_missingFilterA filter condition references a variable that no longer exists.
filter_value_missingFilterReserved. A filter condition references a value that no longer exists. No validation path returns it, see the note below.
filter_value_variable_missingFilterA filter condition's value references a variable that no longer exists.
filter_value_value_missingFilterA filter condition's value references a value that no longer exists.
filter_user_missingFilterA filter condition references a user that no longer exists.
filter_app_missingFilterA filter condition references an app that no longer exists.
filter_record_missingFilterA filter condition references a record that no longer exists.
filter_option_missingFilterA filter condition references a select option that no longer exists.
field_assignment_type_invalidField assignmentA field assignment has an invalid type.
field_assignment_end_date_disabledField assignmentA field assignment sets an end date on a field that has end dates disabled.
field_assignment_variable_missingField assignmentA field assignment references a field that no longer exists.
field_assignment_value_missingField assignmentA field assignment references a value that no longer exists.
field_assignment_value_variable_missingField assignmentA field assignment's value references a variable that no longer exists.
field_assignment_value_variable_invalidField assignmentA field assignment's value references a variable that is not valid here.
field_assignment_value_value_missingField assignmentA field assignment's value references a value that no longer exists.
field_assignment_user_missingField assignmentA field assignment references a user that no longer exists.
field_assignment_app_missingField assignmentA field assignment references an app that no longer exists.
field_assignment_record_missingField assignmentA field assignment references a record that no longer exists.
field_assignment_option_missingField assignmentA field assignment references a select option that no longer exists.
checklist_property_value_variable_missingChecklist propertyA checklist property assignment references a variable that no longer exists.
checklist_property_value_value_missingChecklist propertyA checklist property assignment references a value that no longer exists.
checklist_property_user_missingChecklist propertyA checklist property assignment references a user that no longer exists.
action_invalidActionAn action is invalid.
action_variable_missingActionAn action references a variable that no longer exists.
action_value_missingActionAn action references a value that no longer exists.
action_user_missingActionAn action references a user that no longer exists.
action_app_missingActionAn action references an app that no longer exists.
action_app_invalidActionAn action references an app that is not valid here.
action_view_missingActionAn action references an app view that no longer exists.
action_automation_missingActionAn action calls an automation that no longer exists.
action_automation_invalidActionAn action calls an automation that is not callable here.
action_call_argument_invalidActionAn action passes a call argument that the target automation does not accept.
What about filter_value_missing?

filter_value_missing is still part of the published AutomationBrokenReasonCode type, but no validation path returns it. Treat it as reserved: your code can keep handling it, but don't expect it.

validate checks only meaning, and create and update already reject a malformed value with 400. A value that references a deleted field or variable returns filter_value_variable_missing. A value that resolves to empty isn't a validate fault: it matches every record when the automation runs.

Next steps​