Retry

For free: Requests will be considered failed if not processed within 2 minutes.

For pay-as-you-go: Requests will be considered failed if not processed within 5 minutes.

For fixed pricing: Requests will be considered failed if not processed within Custom(you may timeout as much as needed).

Many things can go wrong in a serverless environment. If your API does not respond with a success status code (2XX), we retry the request to ensure every message will be delivered.

The maximum number of retries depends on your current plan. By default, we retry the maximum amount of times, but you can set it lower by sending the Upstash-Retries header:

cURL

curl -XPOST \
    -H 'Authorization: Bearer XXX' \
    -H "Content-type: application/json" \
    -H "Upstash-Retries: 2" \
    -d '{ "hello": "world" }' \
    'https://qstash.upstash.io/v2/publish/https://my-api...'

import { Client } from "@upstash/qstash";

const client = new Client({ token: "<QSTASH_TOKEN>" });
const res = await client.publishJSON({
  url: "https://my-api...",
  body: { hello: "world" },
  retries: 2,
});

from upstash_qstash import Client

client = Client("<QSTASH_TOKEN>")
client.publish_json({
  "url": "https://my-api...",
  "body": { "hello": "world" },
  "retries": 2
})

The backoff algorithm calculates the retry delay based on the number of retries. Each delay is capped at 1 day.

n = how many times this request has been retried
delay =  min(86400, e ** (2.5*n)) // in seconds

n	delay
1	12s
2	2m28s
3	30m8ss
4	6h7m6s
5	24h
6	24h

Upstash-Retried Header

QStash adds the Upstash-Retried header to requests sent to your API. This indicates how many times the request has been retried.

Upstash-Retried: 0 // This is the first attempt
Upstash-Retried: 1 // This request has been sent once before and now is the second attempt
Upstash-Retried: 2 // This request has been sent twice before and now is the third attempt