JobState Enum

The lifecycle states a background job transitions through, from creation to completion.

Namespace: Zeridion.Flare · Assembly: Zeridion.Flare.dll

public enum JobState
{
    Pending,
    Scheduled,
    Processing,
    Succeeded,
    Failed,
    Cancelled,
    DeadLetter
}

Values

Enum value	API string	Description
Pending	"pending"	Queued and waiting for a worker to claim it.
Scheduled	"scheduled"	Waiting for a future RunAt time or for a parent job to succeed.
Processing	"processing"	Currently being executed by a worker.
Succeeded	"succeeded"	Completed successfully.
Failed	"failed"	Reserved for future use; not set automatically by the SDK. A job transitions directly from Processing to DeadLetter when retries are exhausted. Jobs in DeadLetter state can be manually retried via IJobClient.RetryAsync.
Cancelled	"cancelled"	Cancelled before processing started, or cascaded from a dead-lettered or cancelled parent.
DeadLetter	"dead_letter"	Exhausted all retry attempts and was moved to the dead letter queue.

State machine

The Failed state appears in the enum but is not part of the active state machine — see the note below.

Terminal states

A job is considered terminal when it reaches one of these states — no further automatic transitions occur:

• Succeeded — the job finished without error.
• Cancelled — the job was explicitly cancelled via IJobClient.CancelAsync, or its parent job failed/dead-lettered (cascading cancellation for continuations).
• DeadLetter — the job failed on every allowed attempt. It remains in the dead letter queue until manually retried via IJobClient.RetryAsync or the dashboard.

Failed is reserved and not set automatically by the SDK. When a processing job fails and retries remain, it is reset to Pending with a RunAt delay (exponential backoff). When all attempts are exhausted, the job moves directly to DeadLetter. The Failed value exists in the enum for forward compatibility and possible future hand-managed failure surfaces, but no production code path emits it today — observed job state will always be one of Pending, Scheduled, Processing, Succeeded, Cancelled, or DeadLetter.

API string mapping

The REST API and the SDK use different representations. The API returns lowercase snake_case strings ("dead_letter"), while the SDK uses the JobState enum. The SDK handles this mapping automatically — you never need to parse API strings yourself.

If IJobClient.GetStatusAsync encounters an unrecognized state string from the API, it throws InvalidOperationException.

See also

• JobStatus — the full status object that includes JobState
• IJobClient — methods that create and transition jobs between states
• Retry strategies — how retries and dead letter work