DEV Community

Qixinw Team
Qixinw Team

Posted on Fully Autonomous

Reliable API Publishing: Handle Unknown Outcomes Before Retrying

When a publishing request times out, the most dangerous assumption is that nothing happened.

The remote server may have created the article and lost the response on the way back. Repeating the request can then produce a second public article. A content publishing service should model this uncertainty explicitly.

This article describes a practical design for publishing through a third-party API. The examples are conceptual; they are not claims that every provider implements the same retry or idempotency features.

Separate failure from uncertainty

A useful publication state model has at least these outcomes:

Outcome Meaning Next action
Published A successful response contains a validated article ID and URL Save the receipt
Rejected The provider explicitly rejected the request Correct the reported problem
Rate limited The provider explicitly asks the client to slow down Delay according to the provider's policy
Unknown The request may have reached the provider, but the result is unavailable Reconcile before sending again

Do not treat every non-success response alike. A connection timeout after sending the body is different from a validation rejection. A proxy error may also hide a successful upstream operation.

Freeze the publication intent

Before queuing a request, save a snapshot containing the article version, destination account or organization, and publication options. Keep credentials outside that snapshot.

An internal uniqueness constraint can prevent two workers from submitting the same local intent:

UNIQUE (tenant_id, article_id, article_version, channel_id)
Enter fullscreen mode Exit fullscreen mode

This protects the local queue. It does not make a remote POST idempotent. Only rely on a provider-side idempotency key when the provider documents support for it and its retention window.

Check the worker lease before sending

A worker may lose its lease while waiting for authentication or preparing images. Check ownership again immediately before the external write, and leave enough lease time for the configured request timeout.

load frozen publication
validate destination and credentials
prepare durable public image URLs
verify worker still owns an unexpired lease
send one creation request
persist success, explicit rejection, or unknown outcome
Enter fullscreen mode Exit fullscreen mode

Lease checks and fencing protect local state. They cannot cancel a remote operation that already started. If a process crashes after the provider creates an article but before the receipt is saved, reconciliation is still necessary.

Validate the receipt

A successful status code is useful, but also check the returned article ID, expected author or organization, publication timestamp, and URL origin. Where the API supports it, retrieve the public article separately and compare its title and content.

Store the external ID and URL durably. Do not include API keys in task snapshots, exception messages, or diagnostic reports. Disable automatic credential-bearing redirects unless each destination is explicitly trusted.

Make reconciliation a supported operation

For an unknown result, inspect the account's recent articles using the provider's supported API or interface. Compare destination, title, body, and time window. A title alone is not a unique identifier.

If the original article is found, attach its receipt to the existing task. If absence cannot be established, keep the task unresolved instead of silently retrying. Record who confirmed the resolution and what evidence they used.

Respect content and platform settings

Send only reviewed publication options. Some platforms parse Markdown front matter that can override JSON fields, so treat that metadata as configuration rather than harmless body text.

Use a canonical URL only for the corresponding original article. Images need durable, publicly accessible addresses. For AI-generated writing, use the platform's disclosure mechanism accurately.

The goal is a publication history that can explain what was requested, what the provider confirmed, and what still needs verification.

References: Forem API documentation and DEV's automated-client and AI disclosure guidance.

Disclosure: This article was generated with AI and published as an authorized integration verification. It contains general software design guidance and no product performance claims.

Top comments (0)