Run a retained message's routing decision again

Records who asked, when and why, and the rail runs the same routing decision a new message gets — send journal, ownership map, declared rules — on its next pass. Engines named release the message to them; a declared refusal refuses it, citing the rule; otherwise it stays retained, under the cause the decision found. The operator never chooses the engine. Only a releasable retention can be re-evaluated (JDC-0204 otherwise), and only while it is still retained (JDC-0202). Idempotent per X-Idempotency.

POST /v1/retained/{messageId}/reevaluate

Run a retained message's routing decision again

cURL

curl --request POST \
  --url https://api.example.com/v1/retained/{messageId}/reevaluate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "reason": "<string>"
}
'

202

{
  "channelId": "spb",
  "messageId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "receivedAt": "2023-11-07T05:31:56Z",
  "reevaluatedAt": "2023-11-07T05:31:56Z",
  "releasable": true,
  "retainedAt": "2023-11-07T05:31:56Z",
  "retentionReason": "<string>",
  "reevaluation": {
    "pending": true,
    "reason": "<string>",
    "requestedAt": "2023-11-07T05:31:56Z",
    "requestedBy": "<string>"
  },
  "unassignedKey": {
    "keyKind": "ACCOUNT",
    "keyValue": "<string>"
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Idempotency key; a retry with the same key and body replays the first answer.

Parámetros de ruta

messageId · string<uuid> · requerido

The message's surrogate id, from the listing.

Cuerpo

application/json

reason · string · requerido

Why the decision should be run again. 1 to 512 characters after trimming, with no NUL.

Respuesta

202

application/json

Accepted

channelId · enum<string> · requerido

Opciones disponibles: spb, pix

messageId · string<uuid> · requerido

receivedAt · string<date-time> · requerido

reevaluatedAt · string<date-time> | null · requerido

The last time the rail tried its routing decision again and the message stayed retained, whether the decision ran or failed; null when it never tried.

releasable · boolean · requerido

True when the cause is routing or delivery: no owner in the map, a map that could not answer, an owner disabled or unreachable, no delivery mode declared for its code. Only these are re-checked by themselves once the cause lifts, and only these can be re-evaluated; a Pix retention also clears when the vendor resends it. An UNRECOGNIZED_TYPE of a non-financial code releases once a delivery mode is declared for its code and is not re-checked before that; one of a financial code releases on the re-check after a Courier release reads its destination.

retainedAt · string<date-time> · requerido

retentionReason · string · requerido

reevaluation · object

The last operator request to re-evaluate it; null when nobody asked.

Show child attributes

unassignedKey · object

ACCOUNT_UNASSIGNED only: the key the Courier looked up in the ownership map and found no owner for. Assign it (POST /v1/ownership/assignments) and the message is released on its next re-check: for ACCOUNT, send the text before ':' as branch (empty means a payment account) and the text after it as account; any other kind takes keyValue as shown. A raw key (one the map cannot hold) cannot be assigned; it needs a person. Null for every other reason, and for a Pix leg that waits on an earlier leg of its payment, which no key routes.

Show child attributes