Exceptions
Every domain exception extends WorkflowsException (a RuntimeException) with errorCode(): string, status(): int and context(): array — the code plus the definition key, node or instance where known, what Laravel’s logger adds to a report; never a payload or a secret. Messages are translated (en, sk) and name keys, node ids and basenames, never a PHP class:
| Exception | errorCode() | status() | Thrown when |
|---|---|---|---|
UnknownDefinitionException | unknown_definition | 404 | No definition with the key in this scope (the message names the scope), or no webhook definition with that hook id. |
NoVersionException | no_version | 404 | A dry run or export of a definition with no version yet, or a missing version number. |
SubjectOwnerMismatchException | subject_owner_mismatch | 404 | The subject belongs to another owner (never confirms existence). |
DefinitionNotActiveException | definition_not_active | 409 | A start of a retired definition. |
DefinitionKeyTakenException | definition_key_taken / definition_key_trashed | 409 | The key is taken for this owner (also by a soft-deleted definition: restore it). |
DraftConflictException | draft_conflict | 409 | edit() with a stale $expectedChecksum. |
NothingToPublishException | nothing_to_publish | 409 | publish() without a draft. |
PublishedVersionImmutableException | published_version_immutable | 409 | A write to a frozen column of a published version. |
TriggerMismatchException | trigger_mismatch | 409 | A start path that doesn’t match the version’s trigger (start() on a non-manual definition). |
InstanceNotRetryableException | instance_not_retryable | 409 | Retry of an instance that isn’t failed on a step. |
InstanceNotCancellableException | instance_not_cancellable | 409 | Cancel of a terminal instance. |
InvalidGraphException | invalid_graph | 422 | Publish (or a draft save) of an invalid graph; validationReport(); the message lists the first three problems. |
InvalidTriggerInputException | invalid_trigger_input | 422 | Manual input fails validation; errors(). |
InvalidDefinitionException | invalid_definition_key / definition_needs_subject | 422 | A key outside ^[a-z0-9][a-z0-9._-]{0,99}$; a start without the subject the definition needs. |
InvalidEventKeyException | invalid_event_key | 422 | An emitted key outside the pattern, or an internal @ key. |
InvalidTemplateException | invalid_template | 422 | An import payload that isn’t a valid template. |
InvalidDiffException | invalid_diff | 422 | A diff of versions of two different definitions. |
MissingIdempotencyKeyException | missing_idempotency_key | 422 | A webhook start whose key source is empty. |
MissingTriggeringUserException | missing_triggering_user | 422 | An on_behalf_of start without a user. |
SubjectTypeMismatchException | subject_type_mismatch | 422 | A subject of another registered type than the definition’s. |
UnknownSubjectTypeException | unknown_subject_type / unregistered_subject_model | 422 | An unknown subject type key (suggests the closest); a model with no registered type. |
UnknownStepTypeException | unknown_step_type | 422 | An unknown step type (suggests the closest, or names the package a bridged type needs). |
UnknownCalendarException | unknown_calendar | 422 | An unknown calendar (suggests the closest). |
BusinessCalendarNeverOpenException | calendar_never_open | 422 | No open time within the search window. |
StepAuthorizationDeniedException | authorization_denied | 403 | The authorization hook refused (the policy’s message, if any). |
DuplicateStepTypeException | duplicate_step_type | 500 | Another class registers an existing step key. |
InvalidStepTypeException | invalid_step_key / unsupported_schema_keyword / invalid_schema_pattern / not_a_step_type | 500 | A step type that can’t be registered. |
InvalidWorkflowsConfigurationException (every configuration error) extends the toolkit’s PackageToolkitException, not WorkflowsException: it is a programming error, not an HTTP answer. Handlers throw Steps\StepFailedException (permanent) and Steps\RetryableStepException (retried). Inside a step, any WorkflowsException fails the step permanently with its own error code.
Show your open-source love
This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.
More ways to support, including cryptoBy donating, you agree to our donation terms.
Want this built into your product?
We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.