HTTP retry policies and polling in Workday Orchestrate: how they work and how to configure them

Retries and polling are configured once, in Settings

Orchestrate has two separate mechanisms for calls that do not succeed the first time. A retry policy repeats a request that failed (a 503, a timeout, a SOAP fault). A polling configuration repeats a request that succeeded but reported "not finished yet", until an external job completes. Both are defined under the gear icon, in the orchestration's Settings (on the HTTP Retries and HTTP Polling tabs), and selected on the step that makes the call.

Do not build retries out of loops and counters. Orchestrate has no general delay or wait step to put between attempts: the retry policy is where millisecond backoff and the Retry-After header are handled, and it keeps the configuration in one place every step can reuse. The only other configurable wait, the suborchestration launch delay, counts in whole minutes (see the last section). For the wider design of external calls (rate limits, payload size, what to log), see calling external APIs from Orchestrate.

The setting that decides whether a failed call fails the run

Workday's Define HTTP Retry Policies page carries the most important line on this topic: if you want an unsuccessful HTTP response to make the orchestration fail, you must create a retry policy with a Successful Response Code Ranges entry. Without such a policy, an unsuccessful response does not fail the orchestration.

That explains a common production surprise: the external API returned a 400 or 500, the step "succeeded", and the flow carried on with an error body as if it were data. Give every HTTP call that matters a policy with a success range of 200 to 299 (or the narrower range your API uses), even when you want zero retries. Set Maximum Total Retries to 0 or a small number for that purpose; Workday's Update Service Dates Boomerang sample uses a policy with 3 retries and a 200–299 success range for its report calls.

After the step, branch on the result explicitly where it matters. Workday samples test data.<step>.responseCode.is2xxStatusCode() for this, and a local error handler set to Conditional Outputs gives you isSuccess to branch on without touching a failed step's outputs (accessing a failed step's outputs rethrows the error).

Building a retry policy

On Settings > HTTP Retries, a policy has:

• Name, used to select it on the step.
• Maximum Total Retries, at most 60.
• Default Backoff Strategy: Retry Interval (the first wait, in milliseconds), Increment Factor (2 doubles the wait after each failure) and Max Interval (the ceiling, in milliseconds).
• Successful Response Code Ranges, as above.
• One or more sets of conditions that say when to retry.

A condition is one of: Header, Header Value, Status Code, Status Code Range, Soap (a SOAP fault code), Response Timeout, Connection Timeout, Retry on Any Failure, or Custom (an expression that can use currentStep, the HTTP step's own output). Within a set, all conditions must be true. Across sets, any fully matched set triggers a retry, sets are evaluated in order, and the first matching set decides the backoff and retry count for that attempt.

Each set can override the default backoff with Exponential Interval or Retry-After Header. The Retry-After option honours the server's own wait instruction, with a Max Interval you set as the longest delay Orchestrate will accept from the header.

A practical policy for a rate-limited REST API:

with Maximum Total Retries 5 and a success range of 200–299.

Retry policies apply to Send HTTP Request, Send WWS Pagination API Request and Send Workday API Request. Other steps, including Trigger Integration, Store Document and Find Documents, also have a Retry Settings field on their Settings tab. On Trigger Integration it only retries a failure to launch the child, not a failure of the child integration itself.

Which requests are safe to retry

A retry policy does not know whether the server acted on a request whose response was lost. A timed-out GET can be repeated freely. A timed-out POST that creates something, such as a ticket, a payment or a new worker record in another system, may already have succeeded, and a retry creates a duplicate.

For creates, either keep retries to conditions where the request certainly did not land (Connection Timeout, 429, 503) and leave Response Timeout out, or send an idempotency key if the target API supports one. When a create still fails after retries, read the target system before resending manually; the Orchestrate errors guide makes the same point for runs that report success without doing the work.

Polling an external job until it finishes

Polling is for asynchronous external APIs: you start a job, then check its status endpoint until it says done. On Settings > HTTP Polling:

• Total Polling Duration (Minutes): up to 2880 (48 hours).
• Starting Interval (Minutes): 1 to 60, default 15. The interval doubles after each poll that does not meet the stop conditions, up to 60 minutes.
• Error On Timeout: log an error when the duration runs out, so an error handler can act on it.
• Stop conditions: Header, Header Value, Status Code, Status Code Range or Custom. All of them must be met for polling to stop.

A Custom stop condition can use currentStep, global functions, launch parameters and app attributes, but not the outputs of upstream steps. To check for a job ID you received earlier, put that ID in the URL of the polling request itself, then test the response body in the condition.

If the duration runs out without the conditions being met and Error On Timeout is clear, the orchestration continues with the last polling response as the step's output. Branch on that response, or select Error On Timeout; otherwise a job that never finished looks like one that did.

To use the configuration, open the Send HTTP Request step's Settings tab, select Advanced Mode and choose it under Polling Settings.

Where polling is available, and where it is not

Polling configurations need an Integration System or Business Process orchestration. Polling is only for external third-party systems: Workday's page states you cannot use it with Send Workday API Request to poll Workday APIs.

A Send HTTP Request that polls is a checkpointing step. The current process saves its state while polling runs, and a new process with a fresh 60-minute window (45 minutes before production promotion) resumes afterwards. A long wait therefore does not count against the process limit, only against the run's overall limit (runtime limits on large loads covers both).

The step debugger in Orchestration Builder does not run Send HTTP Request steps that use polling, so test polling with deployed runs.

Waiting on Workday instead of an external system

Because polling cannot target Workday APIs, use the mechanisms Workday provides for its own long-running work:

• Enable Wait for Long Running Response on Send Workday API Request (Advanced Mode) waits up to 1 hour for a REST response and up to 6 hours for a SOAP response. In a loop it forces iterations to run sequentially.
• Trigger Integration and Trigger Business Process pause the orchestration until Workday calls back.
• A Call Suborchestration step has a Suborchestration Launch Delay: select Advanced Mode on the step and set Delay Duration (Minutes) to a number or an expression that returns a number. The range is 1 to 60 minutes, and a value outside it is moved to the nearest end (65 becomes 60, 30 seconds becomes 1 minute). The delay always comes before the suborchestration starts, never after it. It is not available in synchronous orchestrations or from Join Loops.

A status check built from that delay is a design pattern, not a documented Workday feature: a Loop whose body calls a delayed suborchestration that reads the status, with an Early Stop Condition on "complete". Select Force Sequential Processing on that loop. Loop iterations otherwise run in parallel, so every delayed call would start its wait at the same moment instead of one after another.

Prove the retry and polling behave as designed

Point the step at an endpoint you control that returns 503 twice and then 200, run the orchestration and confirm in the run's step output and application logs that it ended with the 200 response. Then make the endpoint return 400 and confirm the run fails at that step rather than carrying on.

For polling, use a job that you can hold in a running state, confirm the step after the poll has not run yet, then release the job and confirm the next step received the final status response. Repeat once with the duration set short and Error On Timeout selected, and confirm your error handler runs.