Picture this: you are building an agent that moves money-like state around in DynamoDB. It has to update several items at once, and if the network hiccups, it has to retry without applying the change twice. You go looking for a contract you can generate a tool from, and you land on the Amazon DynamoDB Transactions API page on APIs.io.
The first thing the post tells you is that this is a small, interesting API. It is only two operations. TransactGetItems groups up to 100 Get actions into one atomic read. TransactWriteItems groups up to 100 write actions across up to 100 distinct items, in one or more tables, in the same account and Region. Either all of them land or none do. Everything else in DynamoDB is one item at a time or best-effort batch, so this is the call where the database makes a promise. For context, DynamoDB itself scores 78.8, exemplar, with Agent Readiness at 36.4, agent-ready.
The page carries an OpenAPI contract, an overlay, a JSON Schema, JSON-LD and a link to AWS's API reference. For the thing you care about, the news is good. The request schema caps TransactItems at 100 and includes ClientRequestToken, described as the identifier that makes the write idempotent. That is the feature your agent needs most: a retried transactional write that does not apply twice. The overlay even phrases the question the way you would: can I retry a transactional write safely without applying it twice?
There is a wrinkle you should know before you generate a client. DynamoDB is not REST. Every call is a POST to a regional endpoint with an X-Amz-Target header of the form DynamoDB_20120810.OperationName. To fit that into OpenAPI, the paths are written as fragments, /#TransactGetItems and /#TransactWriteItems. The post calls this a workaround. It works as a document, but it is a workaround.
Then comes the turn, and it is about the company that wrote the post, not about AWS. The catalog also holds AWS's own Smithy model, dynamodb-2012-08-10.json, which defines 58 operations for DynamoDB. The five OpenAPI splits on APIs.io, covering Batch, Items, Queries, Tables and Transactions, hold 15 between them. The provider record says api_count: 1, while the site builds six API pages.
For TransactWriteItems specifically, the gap is the part that would bite you. Smithy lists nine errors, including TransactionCanceledException, TransactionInProgressException and IdempotentParameterMismatchException. The OpenAPI documents two responses besides 200: a 400 for invalid request parameters and a 409 for a transaction conflict. The cancellation reasons, which are how a caller learns which condition check failed, are not described. And the security scheme declares SigV4 as type http, scheme bearer, when SigV4 is a signature, not a bearer token.
The post is plain about whose fault this is. These are the catalog's defects, not AWS's. The first-party model is right there, and the contract did not use it.
So what do you do with that? You can still trust that the idempotency token is in the contract, and you can still treat the two operations as the right fit for an atomic write. But you should not build your agent's error handling from the OpenAPI alone. If your retry logic needs to tell a cancelled transaction from one still in progress, or a mismatched token from a plain conflict, the AWS Smithy model and API reference are where those answers live today.
The post's own fix is to regenerate the OpenAPI from the Smithy model. That would bring the 43 missing operations, the full error list and a correct SigV4 scheme in one pass, and it would reconcile api_count with the pages the site builds.
Your takeaway: the Transactions API is the right shape for an agent that has to write safely, but the catalog's contract for it currently drops seven of nine errors. Check the source model before you wire up retries.
Read the original: https://apis.io/2026/10/22/dynamodb-transactions-contract-drops-seven-of-nine-errors/