Cancellation and deletion

Operation results / Cancellation and deletion

DELETE /rest/messages/{ids} cancels outgoing messages, while DELETE /rest/incoming/{ids} deletes received messages. The HTTP 200 response contains an array in which status describes the operation result for an individual ID.

Item status and HTTP

A JSON item’s status: 204 or status: 409 describes that individual operation. The HTTP status of the whole response remains 200. A failure of the whole request has an appropriate HTTP status and the application/problem+json format described in the error catalog.

How to read the result

Field / value	Meaning
id	ID of the message associated with this result.
status: 204, error: null	Cancellation or deletion succeeded.
status: 404	The item was not found in the processed batch.
status: 409	The message state prevents cancellation.
status: 500	The item operation failed because of a server problem.
error as an object	Full Problem Details for the failed operation. error.status matches the item’s status, and error.type identifies the problem.

If none of the provided IDs are found, the API can return a failure of the whole request with HTTP 404 instead of a result array.

Response example

For DELETE /rest/messages/123,124, the first message was canceled. The second message’s state prevents cancellation, so its result has status 409 and type message-not-cancellable.

Response headers

HTTP/1.1 200 OK
Content-Type: application/json
X-Success-Count: 1
X-Error-Count: 1

Successful cancellation and a message state conflict

[
    {
        "id": 123,
        "status": 204,
        "error": null
    },
    {
        "id": 124,
        "status": 409,
        "error": {
            "type": "https://api.szybkisms.pl/problems/message-not-cancellable/",
            "status": 409,
            "title": "Message Cannot Be Canceled",
            "detail": "This message can no longer be canceled.",
            "code": "409-2",
            "instance": "/rest/messages/123,124"
        }
    }
]

code is a diagnostic code for support. instance is the path of the whole request; the item’s id identifies the message.

How to handle a batch

1. Check HTTP status and Content-Type. For HTTP 200 with application/json, read the result of every ID.
2. For status: 204 and error: null, mark the operation as completed. Handle other results according to status and error.type.
3. X-Success-Count counts successful cancellations or deletions, while X-Error-Count counts unsuccessful operations.
4. Check the cause before retrying. For a 409 conflict, read the message cancellation requirements; automatic retries do not change the message state.

Message sending and statuses · Message pricing