Skip to content

Retry a failed outbox delivery

POST
/admin/federation/outbox/{id}/requeue

Puts a failed outbox row back in the queue: status becomes queued, attempts goes back to 0, next_attempt_at is set to now and last_attempt_at is cleared. updated_at is also set to now, and last_error is kept.

The row isn’t sent straight away. The delivery worker picks it up on its next pass; it runs every 30 seconds and when new rows are added, and a retry doesn’t wake it. Retrying doesn’t mean the next try will work: if the receiver refused the row for a reason that still holds, it fails again, so read last_error first.

Only a failed row can be retried. Any other status gets 409: a queued row is already waiting, and a sent one would be delivered twice. If someone retries the same row at the same moment, you can get 200 with the row as it now stands, which may already have moved on.

After the change, the server tries to record a federation.outbox.requeued audit event; if that fails, the failure is only logged and the retry still stands. As shipped, this endpoint checks only that you’re signed in: any signed-in user can retry any failed row.

id
required
string format: uuid

The row as it is now, normally queued.

One outgoing delivery: an activity on its way to one peer, or to one user on that peer. The outbox dispatcher creates it from your activities, and the delivery worker sends it.

object
id
required
string format: uuid
activity_id
required

The local activity being delivered.

string format: uuid
peer_id
required
string format: uuid
target_user_url

The user on the peer this delivery is for. Left out when it’s for the whole peer.

string
nullable
status
required

Where delivery stands. The database also has a refused status, for deliveries held back because they needed encryption, but that refusal isn’t in effect yet.

string
Allowed values: queued sent failed cancelled
attempts
required

How many tries have failed with a retryable error. The fifth such failure marks the row failed without adding to the count, so it stops at 4. Retrying the row sets it back to 0.

integer
next_attempt_at
required

When a queued row is next due. Retries wait 30 seconds, 30 seconds, 5 minutes and then an hour. Once a row is sent or failed, this keeps its last value.

string format: date-time
last_attempt_at
string format: date-time
nullable
last_error

What went wrong on the most recent failed try. When the receiver refuses a batch it includes the receiver’s reason; for a single delivery it gives only the HTTP status. It stays after a later try succeeds or the row is retried.

string
sent_at

When the other instance accepted the delivery.

string format: date-time
nullable
delivered_with_key_id

The key ID of the HTTP signature on the delivery that was accepted.

string
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Outbox row not found.

object
error
required

Human-readable error summary

string
Example
the request could not be completed

The row isn’t failed.

object
error
required

Human-readable error summary

string
Example
the request could not be completed