ActivityPub/Primer/HTTP status codes for delivery

The ActivityPub federation protocol uses an HTTP POST request for sending activities to remote servers. The structure of HTTP gives a limited vocabulary of response codes for HTTP requests. These response codes are 3-digit codes; the first digit indicates a class of status (success, redirect, client error, server error), and the final two digits represent details about the reason for that status.

The ActivityPub specification does not specify how the sending server should respond to each possible status code; it leans on well-defined use of these codes in HTTP and RESTful APIs. The following guidelines give recommendations for how to respond to particular codes. The Wikipedia article List of HTTP status codes covers all codes.

Possible behaviours:

- Delivery is complete; no action - Delivery is not complete; no action; treat as still pending - Retry delivery - Fail delivery permanently

1xx codes

These codes are used for managing the low-level connection information.

100 Continue

This is a low-level status code, and many HTTP client libraries will handle it automatically.

101 Switching Protocols

This is used for changing out of the HTTP system to another protocol, like WebSockets. There is not a standard for using ActivityPub over WebSockets, or other protocols, as of this writing in early 2024. Recommendation: if this is received, permanently fail the delivery.

2xx codes

200 OK

This is used for a successful delivery. You can expect that the activity has been delivered to all addressees and that any side effects have already taken place. Recommended behaviour: no action, delivery is complete.

201 Created

This is unusual for the federation protocol, since delivery does not "create" the activity. Recommendation: treat is as a 200 OK response, no action, delivery is complete.

202 Accepted

This is used for queued delivery. The activity has passed some checks (like authentication, correct addressing) but probably has not been fully delivered, or the side effects have not fully been made. Queuing systems for delivery are pretty common on the fediverse and final delivery might take minutes or, in problematic situations, hours or days. Recommended behaviour: treat as still pending.

204 No Content

This is similar to 200 OK, but does not include any messages. Recommendation: delivery is complete, no action.

3xx codes

These codes are used for redirecting an HTTP request to a different URL. Since the inbox or sharedInbox URLs are derived directly from the ActivityPub actor profile, it would be unusual to need a redirect. One possible cause is an actor that has been cached for a long period, and the implementation has changed in the meantime. Recommended behaviour: ignore 3xx code, refetch the ActivityPub actor.

TBD: detailed responses for each 3xx code, for maximum compatibility.

4xx codes

These are client error codes; it means the request is incorrect and needs to be fixed. Some of these might be recoverable; others are not.

400 Bad Request

TBD

401 Unauthorized

This codes means insufficient authentication information has been passed. It typically means that the ActivityPub/Primer/HTTP Signature on the request is missing or malformed. There may be other reasons this would happen; in particular, a developer that mistakes this code for the 403 code. That said, recommended behaviour is: fail delivery permanently, and check your HTTP Signature code. Another option is if there are additional authentication options to try, choose another and retry the request.

403 Forbidden

This code means that the authentication is correct, but that the authenticated user is not allowed to delivery activities to this address. Typically, this would be for a blocked user or domain, although it might also be used for allow-only private federated networks. Recommended behaviour: fail delivery permanently.

404 Not Found

This code is for when the URL is no longer valid. However, at least one ActivityPub implementation uses a 404 code when the delivered activity is not acceptable (it should probably be a 400 code instead). Recommended behaviour: fail delivery permanently. For maximum compatibility, it may make sense to re-fetch the actor and check for a different inbox URL.

405 Method Not Allowed

This is one of the few codes defined in the ActivityPub specification. It means that this URL is not used for ActivityPub federation protocol -- it's only used for reading the user's inbox. Recommended behaviour: fail delivery permanently, and note that this URL is undeliverable. For maximum compatibility, it may make sense to re-fetch the actor and check for a different inbox URL.

410 Gone

This is used when an URL is no longer available and never will be. It's often used when a resource has been deleted; in the case of ActivityPub inboxes, the most likely scenario is that the user's account has been closed permanently. Recommended behaviour: fail delivery permanently, and note that this URL is undeliverable. For maximum compatibility, it may make sense to re-fetch the actor and check for a different inbox URL.