Target Contract

target-configuration.md is the shorter companion: it gives the per-target parameter block and the five rules. This file gives the contract those rules come from, with one working example per target type.

1. Who validates what, and when

Three layers check a subscriber, in this order. Knowing which layer owns a check tells you where a mistake will surface.

Layer 1, the model. Shapes, lengths, patterns, and @required members. It runs before any service code. It is deliberately narrow about targets: TargetArn is typed as a service-neutral ARN (^arn:aws(-[a-z0-9]+)*:[^\s]+$, 1 to 1600 characters), because the supported target services use different resource separators. So the model never rejects a target for being the wrong kind of resource.

Layer 2, the service, before the subscriber is stored. This is where the service checks the invariants it owns. It resolves a target type from the ARN, then applies the rules it needs in order to route, to build a request at all, and to protect itself. Every failure here is an InvalidInputException naming the member, and nothing is persisted.

Layer 3, the target service, at delivery. Existence, reachability, authorization, value ranges, identifier grammars and lengths, sizes, and required fields of the target’s own API.

The line between layer 2 and layer 3 is one rule, and it is narrower than it looks:

Layer 2 checks only what the service itself needs, plus generous anti-abuse ceilings. It does not hold a second copy of the target API’s parameter grammar. Anything belonging to the target — its ranges, its identifier rules, its vocabularies — is checked by the target, when it is invoked.

That boundary is deliberate. A rule the service copies from a target is enforced twice, and the two copies drift: when the target widens a rule, the copy rejects a value the target would have accepted, and the customer gets an error for a request that was fine. So the copy is not made.

Three consequences follow, and all three are common surprises.

1. A target ARN is checked for shape, type, region, partition and account, never for existence. A well-formed ARN naming a queue that does not exist is accepted, and becomes a delivery-time failure. A wrong region or partition is a different matter and is rejected at create: TargetArn must be in region us-east-1, TargetArn must be in partition aws. Only a new-custom-bus and a universal target are exempt from the region check.
2. A JSONata expression is checked for syntax, not for its result. Create-time acceptance of an expression is no evidence it is correct; it is not evaluated until an event arrives.
3. A value the target will reject is accepted in either form. A DelaySeconds of 999999 and of {% 999999 %} are both stored, and SQS rejects both at delivery with a 400 InvalidParameterValue. The accepted range is SQS’s, so the service does not carry it. The same holds for a member the target requires and you omitted, and for one the target does not accept on the resource you named: as long as the SDK can serialize what you sent, the service forwards it and the target decides.

What layer 2 actually checks

Resolved from the ARN’s service and resource type, so this list is also the set of supported targets:

An ARN whose service is not in that table is rejected with InvokeConfiguration.TargetArn: TargetArn is not a supported subscriber target. A recognised service whose resource part has the wrong shape names the shape it wanted instead, for example InvokeConfiguration.TargetArn: TargetArn resource must be of the form stream/{name}. Each form’s delimiter is pinned, so deliverystream:name is rejected where deliverystream/{name} is required, and a form written without [:{qualifier}] rejects a trailing element.

Those shape rules are structural only, and no character is reserved. A queue named queue?name or queue*name is accepted, because the resource part carries neither / nor : and so parses as a bare queue name. The * in an execute-api ARN is a non-blank path segment like any other, not a wildcard. Neither is a useful thing to do; the point is that a create call will not stop you.

Given the resolved type, the service checks two groups, and nothing outside them.

1. Routing — can the service reach this target at all.

• Every parameter block you supply must match the resolved target. Each target type accepts exactly one block, so this one rule also covers supplying two: one of the two cannot match. The message names the offending block and the expected one, for example SnsParameters is not supported for target arn:aws:sqs:us-east-1:111122223333:orders. Expected SqsParameters. A target that takes no block at all — a classic bus, or Firehose — reads Expected no target parameters. The block must match because the invoker is chosen from the ARN, so a mismatched block would be stored and never read.
• The target is in the caller’s account. Target resource account (X) must match the subscriber account (Y). Unlike the ARN messages above, this one carries no field-name prefix.
• The target is in the endpoint’s region and partition, except for a new-custom-bus or universal target, which are exempt from the region check.
• The target is not the subscriber’s own bus. InvokeConfiguration.TargetArn must not reference the subscriber's own event bus, because delivering to the source bus re-publishes and re-matches forever. The check is exact string equality, so it catches only the identical ARN and not some other bus that forwards back.

2. Rules that protect the service itself.

• Every JSONata expression must parse, because the service evaluates it once per delivered event. An expression that fails only at delivery is invisible to the caller.
• An API Gateway header name must be a literal, and must not be one the service signs. Authorization, Host, and any header prefixed X-Amz are rejected, case-insensitively, because the request is signed with SigV4 and overriding a signed header invalidates the signature. This is not API Gateway’s reserved-header list, which API Gateway owns and enforces itself. The rule is scoped to API Gateway. An API destination also takes HttpParameters, and its header names are not checked at all — neither for being literal nor for being signing-sensitive.
• A BinaryValue must not contain {% or %}, because it is forwarded unevaluated and an expression would arrive at the target as its own literal text. The test is for either delimiter anywhere in the value, so a literal that merely contains one is rejected too.
• 1 MiB of UTF-8 per message-attribute map, counting each entry’s name, DataType, StringValue and BinaryValue text. MessageAttributes and MessageSystemAttributes are measured separately rather than summed, and a BinaryValue counts its Base64 text rather than its decoded bytes. This is an anti-abuse ceiling well above any target’s own budget, so the target is still what rejects an oversized set.
• A message-attribute map must not hold a null attribute object. A null there is not a value the SDK can serialize; it is a hole the service would dereference while building the request.

Not checked here, because they belong to the target: whether a member the target’s API requires is present, whether a member applies to the standard or FIFO resource you named, SQS’s delay range and its refusal of a per-message delay on a FIFO queue, SNS’s MessageStructure vocabulary, Lambda’s durable-execution-name and tenant-id grammars, whether a Lambda qualifier names a version or an alias that exists, FIFO group-id and deduplication-id requiredness, emptiness, length and character rules, Kinesis’s partition-key requiredness and length, message-attribute names against SQS’s and SNS’s own naming rules, DataType requiredness, attribute counts and data-type vocabularies, the Base64 contract, and reserved system-attribute names.

RoleArn is not checked for account here. CreateSubscriber authorization enforces iam:PassRole on it first, which rejects a role you cannot pass with AccessDeniedException before validation runs.

2. Required request fields

Unconditionally required by the model on CreateSubscriber:

Required conditionally, by the service:

Everything else is optional, and three optional members are worth treating as mandatory in practice: OnFailureConfiguration, LogConfiguration, and RetryPolicy. The first two are why a failure is visible at all, and every example below sets them.

Target-required runtime fields

These are the target API’s own required fields. The service does not check them at create. The target service checks them at delivery — including a FIFO MessageGroupId, which the service no longer requires at create. A .fifo queue or topic with no group id is stored, and SQS or SNS rejects every delivery.

The target also decides applicability: whether a member is accepted on the resource you named. MessageDeduplicationId on a standard queue, an SNS group or deduplication id on a standard topic, and a per-message DelaySeconds on a FIFO queue are all stored and dealt with when the target is called.

For the typed target blocks the service builds the request, so you only supply the parts the block exposes.

3. Literal versus JSONata

Most scalar target parameters are modelled as strings so they can carry either a literal or a JSONata expression in {% ... %} form. The expression is evaluated once per delivered event, with the event available as $events (addressing is in filters-and-expressions.md).

Both forms are checked the same way, and it is a short check. A literal is checked only against the rules the service owns; an expression is additionally required to parse. Neither is checked against the target’s own range or grammar, and neither is checked for being required or for applying to the resource you named. So for most members the create call tells you nothing about whether the value is acceptable — the target decides that at delivery.

InvocationTimeoutSeconds is the one range the service does hold, because the service is what makes the call and holds the connection open. It is a service-owned limit, not a copy of a target’s. Three details do not follow from that: on HttpParameters it is valid for an API Gateway target and rejected for an API destination; a universal target refuses an expression outright and requires an integer; and on any other block an expression skips the create-time range check entirely and is clamped at delivery. The upper bound is resolved from service configuration at runtime rather than compiled in, so treat 30 as the documented default rather than a fixed ceiling.

Beyond the two InvocationType members and the universal target’s InvocationTimeoutSeconds above, two more members must be literals and reject an expression outright:

• HttpParameters.HeaderParameters keys, on an API Gateway target. A header name MUST be a literal so it can be inspected at all, and an expression is rejected on that ground. A name that is Authorization, Host, or X-Amz-prefixed is rejected because the request is signed with SigV4 and those are the headers the signature covers. API Gateway’s own reserved-header list is longer and is enforced by API Gateway, at delivery. Neither check runs for an API destination, which takes the same block: there a header name may be an expression and may be one of the signing headers.
• MessageAttributes.*.BinaryValue. It is forwarded unevaluated, so an expression would reach the target as its own literal text. The rejection triggers on {% or %} appearing anywhere in the value, not only on a well-formed expression.

One member is neither evaluated nor guarded: MessageAttributes.*.DataType is forwarded exactly as written and is not validated at all. An expression there is not rejected; it arrives at the target as its own text and the target rejects the data type.

Message-attribute names are evaluated per event. For SQS and SNS, both an attribute’s name and its StringValue may be expressions. The failure modes differ: a name that resolves to nothing fails the whole delivery, as do two names that resolve to the same string, while a StringValue that resolves to nothing is delivered as a null value. Create-time syntax checking of a name is conditional — a malformed expression is caught only if its {% and %} delimiters are both intact. {% $events.Data fails the delimiter test, is treated as a literal name, and reaches SQS or SNS as that text.

Per-message fields belong in an expression. A message group id, a deduplication id, a partition key, and an execution name are per-message by nature. A literal deduplication id is accepted and makes the target treat every message after the first as a duplicate; the symptom is exactly one message arriving and then nothing. The canonical forms derive them from the event’s own ordering fields:

Limits: Transformer.JsonataConfiguration.Expression is 1 to 8192 characters and must match {% ... %} with nothing after the closing delimiter.

A create rejected on invocationType is the enum’s casing

The InvocationType rows above produce the one create-time rejection people copy into tickets. Verbatim:

The value is an enum, upper case: EVENT or REQUEST_RESPONSE. The rejected value is usually Event, the casing Lambda’s own Invoke API uses, or a JSONata expression, which this member does not accept. The Lambda member path form is identical with lambdaParameters in the path.

4. Working examples

Nine target types. Each is a complete CreateSubscriber request body, and each sets an SQS dead-letter queue, subscriber logging, and lists the delivery-role actions. Substitute your own partition, region, and account. Read the subscriber back with DescribeSubscriber afterwards: CreateSubscriber returns identity and state only, never the stored configuration.

Every example carries this pair, so it is elided from the bodies below to keep them readable:

LogConfiguration.Level defaults to OFF, so set it before you need it. The dead-letter queue ARN is shape-checked at create, and its queue-name grammar is SQS’s own: 1 to 80 characters of [A-Za-z0-9_-], where a .fifo suffix counts toward the 80.

Every role below also needs sqs:SendMessage on the dead-letter queue. Granting the target but not the dead-letter queue loses the failure entirely: deliveries fail, the failure record cannot be written, and no surface records it.

Standard SQS queue

Role: sqs:SendMessage on the queue. Delivery is SendMessageBatch. SqsParameters is optional on a standard queue; omitting it delivers the payload with no attributes. MessageDeduplicationId is FIFO-only, and SQS is what says so: setting it here is accepted at create and fails at delivery. The attribute count limit, the requiredness of each attribute’s DataType, the accepted data types, and the real size budget are SQS’s and are enforced when the queue is called; the service applies only a generous aggregate byte ceiling and a rejection of a null attribute object. The accepted MessageSystemAttributes names are SQS’s too — AWSTraceHeader is the one it takes.

FIFO SQS queue

Role: sqs:SendMessage on the queue. The service accepts any subscriber Type for this target. SQS still requires MessageGroupId and refuses per-message DelaySeconds on a FIFO queue, so an incompatible configuration fails during delivery. The group id above is not optional in practice; SQS is what enforces it.

SNS topic

Role: sns:Publish on the topic. Delivery is PublishBatch. Nothing about the FIFO pairing is checked at create. On a standard topic a MessageGroupId or a MessageDeduplicationId is accepted and SNS rejects the publish; on a .fifo topic an absent MessageGroupId is accepted and SNS rejects the publish. The accepted attribute data types, each attribute’s DataType requiredness, and the total size budget are SNS’s own, so MessageStructure and an attribute type are both create-time no-ops here.

Size is the binding constraint here, and it fails silently. SNS caps the enveloped message at 256 KB, so a payload at or above roughly 250 KB is accepted by the publish call and never arrives. Around 200 KB delivers normally.

Lambda function

Role: lambda:InvokeFunction on the function. Lambda owns the ARN resource subtype, region, partition, qualifier, DurableExecutionName, and TenantId. The service accepts their literal values after shape and expression syntax checks; Lambda rejects unsupported combinations during delivery. InvocationType is the exception: the service accepts only EVENT or REQUEST_RESPONSE at create, and delivers the value in Lambda’s own vocabulary.

A Lambda returning batchItemFailures in a 200 response retries only the reported entries (§5).

Kinesis data stream

Role: kinesis:PutRecords on the stream. KinesisParameters may be omitted or empty. The invoker still constructs PutRecords, and Kinesis owns PartitionKey requiredness plus both members’ formats and ranges. Missing or invalid values are reported through retries, the DLQ, and, when enabled, subscriber logs.

Step Functions state machine

Role: states:StartExecution, plus states:StartSyncExecution if you set InvocationType: REQUEST_RESPONSE. Name must be unique per account, region, and state machine, so derive it from the event. A literal Name causes every execution after the first to be rejected by Step Functions as a duplicate.

HTTP: API destination and API Gateway

Role: events:InvokeApiDestination on the API destination ARN. PathParameterValues are substituted in order into the endpoint path’s placeholders. Header names and values may both be expressions here, because the header rules below are enforced for API Gateway only.

For API Gateway, change TargetArn to arn:aws:execute-api:us-east-1:111122223333:{apiId}/{stage}/POST/orders, grant execute-api:Invoke, and you may add "InvocationTimeoutSeconds": "20". Two differences bite here:

• Within HttpParameters, InvocationTimeoutSeconds is valid for API Gateway and rejected for an API destination: InvocationTimeoutSeconds is only supported for API Gateway HTTP targets. The member also exists on the Lambda, Step Functions and universal-target blocks, so that message is about this block rather than about the service as a whole. A literal is range-checked and rejected out of range rather than clamped, because the service holds the connection and so owns the range.
• The service rejects only the headers it signs, case-insensitively: Authorization, Host, and any header prefixed X-Amz, and it also requires the name to be a literal so it can check it. It signs the API Gateway request with SigV4, and a customer override of a signed header invalidates that signature. API Gateway’s own reserved-header list is longer, and API Gateway enforces it — a name like Connection, Content-Length, TE, or X-Forwarded-For is accepted at create and dealt with by API Gateway at delivery. Neither check applies to an API destination.

Firehose delivery stream

Role: firehose:PutRecordBatch on the delivery stream. Delivery is PutRecordBatch. Firehose takes no parameter block, so InvokeConfiguration is exactly TargetArn and RoleArn. Supplying any block is rejected: SqsParameters is not supported for target arn:aws:firehose:... Expected no target parameters. Everything outside InvokeConfiguration still applies — filter, transformer, BatchConfiguration, dead-letter queue, logging, ordering Type, StartingPosition, RetryPolicy. The ARN’s resource part must be exactly deliverystream/{name}: the colon form is rejected, as is a trailing qualifier. Batches are capped at 500 records and about 4 MiB.

Two cautions specific to this target. Records are written as the raw payload bytes with no separator, newline, or envelope added, so a downstream consumer that expects newline-delimited JSON will see concatenated records unless the payload itself ends in a newline. And this target has less operational mileage than the others here, so verify a delivery end to end before depending on it.

Another new custom event bus

Role: events:PutEvents and events:PutRawEvents on the destination bus. Forwarding is authorized per event at ingestion against the destination bus’s resource policy, and the action is chosen from the event’s own system metadata: a genuine AWS or partner event needs events:PutEvents, and anything you originated needs events:PutRawEvents. A forwarder carrying both kinds and granted only one silently loses half the stream. See authorization.md.

Metadata holds at most 100 keys. A target that is verbatim the subscriber’s own bus is rejected at create, because it would loop; a different bus that forwards back to this one is not detected, so you own avoiding that cycle.

5. Target and runtime error taxonomy

Delivery failures fall into classes, and the class decides whether the event is retried, dead-lettered, or dropped. Working through the classes in order is faster than reading a message cold.

Where the failure happens

The fault column says who can act on the failure. The retry column says what the delivery path does, and the important part is that it is almost the same for every row: failures are retried by default, and being permanent does not exempt one.

Four of these are worth spelling out.

A permanent fault is retried anyway. There is no class that dead-letters on the first attempt on its own. A 4xx, an expression that throws, and a request that cannot be converted are each retried until MaxRetryAttempts or MaxEventAgeInSeconds is reached, and only then dead-lettered. Retrying cannot fix any of them, so the retries buy nothing and cost the whole window. If you want a first-attempt dead-letter — when testing a failure path, or for a target whose 4xx you know is final — set MaxRetryAttempts: 0.

A service fault is the one class that never exhausts. It retries indefinitely rather than dead-lettering, on the reasoning that the customer cannot act on it and the event should not be discarded for a defect on this side.

HTTP 200 is not success for a batch target. Delivery to SQS, SNS, Kinesis, and Firehose uses the batch APIs — SendMessageBatch, PublishBatch, PutRecords, PutRecordBatch — and each can return HTTP 200 carrying a list of individually failed entries. The invoker reads that list and retries the failed entries alone, so a partially failing batch neither succeeds nor fails as a unit. The same shape exists for Lambda: a function returning batchItemFailures in its 200 response has only those items retried. When you are counting deliveries, count at the target, never from an HTTP status.

A transformation or conversion failure never reaches the target. It is classified before the wire call, so there is no http_status and no target request id in the log record. An empty details.target_request_id on a failed attempt is the signal that the failure was local. A transformation failure is reported as its own EVENT_TRANSFORMATION_FAILURE record rather than a delivery attempt.

Retries and dead-lettering

RetryPolicy has three members, and delivery stops at whichever limit is reached first:

With the defaults, a failing delivery is attempted MaxRetryAttempts + 1 times and stops at whichever limit is reached first, so “nothing arrived” is only a sound conclusion once MaxEventAgeInSeconds has elapsed — for a permanent fault as much as a retriable one. The attempts cap is evaluated before the age cap, so when both are hit the record reports MaximumRetryAttempts.

OnFailureConfiguration.Arn names the SQS queue that receives the failure record, and SQS is the only supported destination. Read the subscriber back and confirm the field is populated; other nestings of it are accepted and stored empty.

The dead-letter record

One record per failed batch, carrying a reference per event:

How to read it:

Two limits. failedMessages carries no payload, so the record alone cannot reconstruct the event; you need the event still inside the bus’s retention window. And deduplicationId is populated whenever the event carried one, including for an UNORDERED subscriber — ordering mode and publish-time deduplication are independent, so its presence says nothing about Type.

Vended logs

Set LogConfiguration.Level to INFO and reproduce, rather than waiting out the retry window. Each attempt produces one EVENT_DELIVERY_ATTEMPT record per event; details.target_input shows what the target actually received, and error.error_code with error.error_message is the same pair the dead-letter record carries. Full field list in observability.md.

6. Troubleshooting flow

Work down. Each step either explains the failure or eliminates a class.

1. Did CreateSubscriber succeed? If the failure is an InvalidInputException, the message names the member. Fix that member; nothing was stored.
2. Wait past the retry window. More than 5 minutes on the defaults, or past MaxEventAgeInSeconds. Before that, a failing delivery is still being retried.
3. Confirm events reached the bus. PublishEventsEntryCount in AWS/EventsV2. Zero means the problem is upstream and nothing below matters. The EventBus dimension value is {name}/{generatedId}, not the ARN.
4. DescribeSubscriber. Check State is RUNNING, and check Revoked. A revoked subscriber delivers nothing while still reading RUNNING, and revocation is terminal.
5. Is anything failing at all? Turn on logs at INFO with IncludePayload: FULL, reproduce, and read details.outcome.
   • No records at all — the event is not reaching the subscriber. The cause is the filter, the starting position, or the addressing asymmetry between the two publish APIs. Go to delivery-troubleshooting.md steps 4 and 5.
   • Records with outcome: FAILURE — continue.
6. Read error.error_code and error.error_message, then classify with §5. Do not use the attempt count to tell a permanent fault from a retriable one: both are retried on the same budget. The message distinguishes them.
   • A 5xx or a throttle: the target is unhealthy or rate-limited. Raise MaxRetryAttempts, or fix the target.
   • CUSTOMER_VALIDATION: your request or expression. Read the message; retries will not help, so MaxRetryAttempts: 0 gets you the record faster while you iterate.
7. Read details.target_input. This settles every expression question, because it is what the target received rather than what you meant to send. An empty or missing field there is an addressing mistake in your expression, not a target problem.
8. Empty details.target_request_id on a failure means the call never left: an input-evaluation or local-conversion fault. The expression or the resolved request is wrong.
9. AccessDenied in the message means the delivery role is missing the target’s action — or, if nothing is observable anywhere, missing sqs:SendMessage on the dead-letter queue.
10. Still nothing. Add a second subscriber with Transformer: { Type: WITH_METADATA }, no filter, and an SQS queue you own. That delivers the event exactly as the service holds it and settles the addressing question outright.

7. Authoritative AWS references

Limits and quotas change, so read them at the source rather than from a copy. Each target’s own API reference is where the required fields and value ranges live, and each service’s quota page is where the numbers live.

Target APIs the service calls

• SQS SendMessageBatch — https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/API_SendMessageBatch.html (opens in a new tab)
• SNS PublishBatch — https://docs.aws.amazon.com/sns/latest/api/API_PublishBatch.html (opens in a new tab)
• Lambda Invoke — https://docs.aws.amazon.com/lambda/latest/api/API_Invoke.html (opens in a new tab)
• Kinesis PutRecords — https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html (opens in a new tab)
• Firehose PutRecordBatch — https://docs.aws.amazon.com/firehose/latest/APIReference/API_PutRecordBatch.html (opens in a new tab)
• Step Functions StartExecution — https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html (opens in a new tab)
• Step Functions StartSyncExecution — https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartSyncExecution.html (opens in a new tab)

Quotas and limits

• SQS — https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-quotas.html (opens in a new tab)
• SNS — https://docs.aws.amazon.com/sns/latest/dg/sns-quotas.html (opens in a new tab)
• Lambda — https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-limits.html (opens in a new tab)
• Kinesis — https://docs.aws.amazon.com/streams/latest/dev/service-sizes-and-limits.html (opens in a new tab)
• Firehose — https://docs.aws.amazon.com/firehose/latest/dev/limits.html (opens in a new tab)
• Step Functions — https://docs.aws.amazon.com/step-functions/latest/dg/limits-overview.html (opens in a new tab)
• API Gateway — https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html (opens in a new tab)

Reference material for the surrounding concepts

• FIFO queue message grouping and deduplication — https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html (opens in a new tab)
• SNS FIFO topics — https://docs.aws.amazon.com/sns/latest/dg/fifo-topic-code-examples.html (opens in a new tab)
• Lambda partial batch responses — https://docs.aws.amazon.com/lambda/latest/dg/services-sqs-errorhandling.html (opens in a new tab)
• iam:PassRole — https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_passrole.html (opens in a new tab)