Reliability
What happens between your API call and the platform.
We never send the same post twice on our own, and we tell you when a platform's response is ambiguous. This page shows the rules behind that sentence.
01States
A target is always in one state.
Each target of a post has its own status. These are the moves it can make, read from the same table the scheduler uses.
- 01draft to scheduledA post with mode schedule or queue, or publishing a draft
- 02scheduled to publishingThe workflow claim step wins the compare-and-set
- 03scheduled to cancelledDELETE /posts/{id}
- 04publishing to publishedThe platform confirmed it with a media ID, a published status or a completed status
- 05publishing to failedA pre-flight failure after the claim, a definite rejection, or a container error or expiry, nothing went live
- 06publishing to unconfirmedAn ambiguous publish response that reconciliation could not settle
- 07unconfirmed to publishedA late reconciliation read, or you resolve it
- 08unconfirmed to failedA late reconciliation read, or you resolve it
- 09failed to scheduledYou edit the post or retry it, which starts a new revision
- 10unconfirmed to scheduledYou edit the post or retry it with includeUnconfirmed, which starts a new revision
- draft
- Saved, not scheduled.
- scheduled
- Waiting for its due time.
- publishing
- The publish call has been claimed.
- published
- The platform confirmed it.
- cancelled
- Cancelled before it started.
- failed
- Nothing went live.
- unconfirmed
- Sent, and the platform's answer was unclear.
The post's status comes from its targets. All published is published, all failed is failed, and all unconfirmed is unconfirmed, never shown as failed. Any other mix is partial.
02Guarantees
Four guarantees, and nothing more.
These are the promises. We do not promise more, because a platform can publish a post and fail to tell us. That is what the fourth one is for.
| Guarantee | What you can rely on | Where you see it |
|---|---|---|
| 01 At most one publish call | Relay Port makes the platform's publish call at most once per target revision on its own. A new revision exists only when you edit or retry the post. | The target's timeline, GET /posts/{id}/events |
| 02 Same key, same post | A repeated API call with the same Idempotency-Key returns the same post, so your code can retry a request that timed out. | The response header Idempotent-Replayed: true |
| 03 A 24-hour duplicate guard | Identical content to the same account within 24 hours is refused, unless you set allowDuplicate to true. | 409 DuplicateContent |
| 04 Ambiguous means unconfirmed | When a platform's answer is ambiguous, the target becomes unconfirmed and the evidence is attached to it. | status unconfirmed, with error.evidence |
Read the details in Idempotency and duplicates.
03Instagram
When Instagram's answer is unclear, we read. We do not resend.
Reconciliation is made only of reads. None of them can create a post, so none of them can duplicate one.
- 01The publish call fails or times out after it may have reached Instagram.
- 02We read the status code of the media container.
- 03We read the account's recent media, from a little before the call was sent, and look for a match.
- 04We check again with waits in between, for a limited time.
- 05The result is published, not published, or undetermined, each with the evidence behind it.
- Published
- The target becomes published.
- Not published
- The target becomes failed. A retry is safe.
- Undetermined
- The target becomes unconfirmed.
04Unconfirmed
What unconfirmed means.
Instagram may have published the post. We could not prove it either way, so we did not send it again, and we did not call it failed.
Look at the account. Then call POST /posts/{id}/targets/{targetId}/resolve with outcome published or failed.
Retrying with includeUnconfirmed is the only way to send it again, and that is your decision.
Read Unconfirmed targets.
05Retries
Retries happen only before the publish call.
Steps that cannot create a public post are retried. The step that can is not.
Retried
- Claiming the target for publishing
- Checking the post, the account and the media again
- Waiting for the platform's rate limits
- Refreshing the access token
- Creating the media containers
- Polling until the media is ready
- The reads that reconcile an unclear answer
- Fetching the permalink and recording the result
Never retried
- The publish call itself
06Webhooks
How webhooks are delivered.
Deliveries follow the Standard Webhooks specification. They arrive at least once and in no fixed order, so deduplicate on webhook-id.
- Every delivery carries the headers webhook-id, webhook-timestamp, webhook-signature.
- Reject a signature whose timestamp is more than 5 minutes away from your clock.
- Answer with a success status code within 10 seconds.
- A failed delivery is retried 10 times, after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 3 hours, 6 hours, 12 hours, 1 day, 1 day.
- An endpoint that keeps failing for 3 days is marked failing.
- After 7 days it is disabled, and the workspace's owners and admins are emailed.
Events
Publishing
- post.scheduled
- A post was scheduled for later.
- post.updated
- A scheduled post was edited.
- post.cancelled
- A scheduled post was cancelled before any target started publishing.
- post.target.publishing
- Publishing started for one target of a post.
- post.target.published
- One target of a post was published.
- post.target.failed
- One target of a post failed and nothing was published to it.
- post.target.unconfirmed
- The platform did not confirm one target. It was not sent again; check the account before retrying.
- post.target.resolved
- An unconfirmed target was marked published or not published.
- post.published
- Every target of a post was published.
- post.partial
- A post settled with some targets published and others not.
- post.failed
- Every target of a post failed.
Connections
- account.connected
- A social account was connected or reconnected.
- account.disconnected
- A social account was disconnected.
- account.action_required
- A social account needs an action on the platform before it can publish.
- account.reconnect_required
- A social account must be reconnected before it can publish.
Media
- media.ready
- An uploaded media file passed its checks and can be attached to posts.
- media.failed
- An uploaded media file failed its checks.
Webhooks
- webhook.test
- A test event sent to one webhook endpoint.
Billing and usage
- billing.past_due
- A payment failed and the 7-day grace started.
- billing.blocked
- The grace ended and new posts and connections are paused.
- billing.recovered
- The open invoice was paid and service resumed.
- usage.threshold
- A usage meter reached 80% or 100% of its plan limit
Read Webhooks.
07Retention
How long delivery logs are kept.
Webhook delivery logs and request logs are kept for the log retention of your plan.
| Plan | Retention |
|---|---|
| Free | 7 days |
| Pro | 30 days |
| Business | 90 days |
| Enterprise | 90 days |
08Half-fail
A post where one account fails.
A post to two Instagram accounts, A and B.
- 01You send POST /posts with an Idempotency-Key. The call returns 201 and both targets are scheduled.
- 02Account A's target reaches published, and post.target.published is sent to your webhook endpoint.
- 03Account B's target is rejected before anything reaches Instagram, for example because a carousel has too few items. It becomes failed with the platform's reason, and post.target.failed is sent.
- 04The post's status is partial: one target published, one failed. post.partial is sent.
- 05You fix the media and call POST /posts/{id}/retry. Only the failed target starts a new revision. Account A's target is not touched.
If account B's target had been unconfirmed instead, the post would still be partial. Its target would carry the evidence, and you would check the account before retrying.
09Measured
What we have measured.
A figure appears here only when it has been measured, with its date and its method.
No measured figures yet.