/aws-serverless

Orchestration Reference

Step Functions and EventBridge decision matrices, error semantics, and limits. Assumes you can write Amazon States Language (Saga/Parallel/Map/Choice JSON) and EventBridge patterns — this file focuses on the choices and gotchas.

Contents

• Standard vs Express
• State machine limits and patterns
• Error handling
• EventBridge rules, pipes, and patterns
• Step Functions vs Lambda durable functions

Standard vs Express

Express sub-types: Async (fire-and-forget, results via CloudWatch Logs); Sync (blocks until completion, invokable from API Gateway/Lambda/StartSyncExecution, 5-min max).

State machine limits and patterns

• Payload limit: 256 KiB between states — store large data in S3, pass S3 keys.
• Inline Map: max 40 concurrent iterations, same execution.
• Distributed Map: up to 10,000 parallel child executions, reads from S3 (JSON/CSV/inventory), supports ItemBatcher/ItemReader/ResultWriter. Standard workflows only.
• 25,000 execution-history entries (Standard) — split long workflows into child executions.
• Parallel state output is an array (one element per branch); all branches must succeed or the state fails.
• Choice state: always include a Default branch.

Common patterns (write the ASL directly): Saga (each step has a compensating undo via Catch, chained in reverse); Parallel (concurrent branches); Map (iterate an array); Agentic AI loop (bedrock:invokeModel → Choice on stop_reason = 'tool_use' → execute tool → loop). Prefer direct SDK integrations (200+ services) over Lambda intermediaries to cut latency, and prefer JSONata for inline transforms over a Lambda task.

Error handling

Built-in error names

States.ALL does NOT catch States.DataLimitExceeded or States.Runtime. These are terminal and must be designed around, not retried.

Retry config

"Retry": [
  { "ErrorEquals": ["States.Timeout"], "IntervalSeconds": 3, "MaxAttempts": 2,
    "BackoffRate": 2.0, "MaxDelaySeconds": 30, "JitterStrategy": "FULL" },
  { "ErrorEquals": ["Lambda.ServiceException", "Lambda.SdkClientException"],
    "IntervalSeconds": 1, "MaxAttempts": 3, "BackoffRate": 2.0 },
  { "ErrorEquals": ["States.ALL"], "IntervalSeconds": 1, "MaxAttempts": 3, "BackoffRate": 2.0 }
]

Defaults: IntervalSeconds 1, MaxAttempts 3 (0 = never), BackoffRate 2.0, JitterStrategy "NONE".

Rules and best practices:

• States.ALL must be last in the Retry array; retries are attempted before catchers.
• Retries count as state transitions (billed in Standard).
• Always set TimeoutSeconds on every Task; always retry Lambda.ServiceException / Lambda.SdkClientException.
• Use JitterStrategy: "FULL" to prevent thundering herd; HeartbeatSeconds for long tasks.
• Catch with ResultPath: "$.error-info" preserves the original input alongside the error (without it, error output replaces the input).
• Listen for top-level execution failures via EventBridge (source: aws.states, detail-type: Step Functions Execution Status Change, status: [FAILED, TIMED_OUT, ABORTED]).

EventBridge rules, pipes, and patterns

Event patterns

All specified fields must match (AND); values within an array are OR'd. Operators: exact ["value"], {"prefix"}, {"suffix"}, {"anything-but"}, {"numeric": [">", 0, "<=", 100]}, {"exists": true}, {"wildcard": "prod-*-east"}.

Best practices

1. Dedicated event bus per application domain — default bus for AWS service events only.
2. Be precise with patterns — broad patterns risk infinite loops.
3. One target per rule — simplifies debugging and IAM.
4. DLQs on all targets.
5. Use the EventBridge Sandbox to test patterns before deploying.
6. For a new event-driven workload, evaluate the enhanced custom event bus first — see the amazon-eventbridge-event-bus skill (see SKILL.md routing). The practices above apply to the classic bus, whose rules and targets do not exist on the enhanced bus.

Pipes vs Rules

Pipes filtering happens at the source — you pay only for matched events — with built-in retry + DLQ.

Step Functions vs Lambda durable functions

Lambda durable functions let you write reliable multi-step workflows as plain code (TS/Python/Java) with automatic checkpointing — the SDK persists each step and replays from the checkpoint on interruption, enabling executions up to 1 year with zero compute during waits. For full guidance use the aws-lambda-durable-functions skill (see SKILL.md routing).