---
title: "Create a Retry Policy"
method: POST
path: "/retry-policies"
tags: ["Retry Policies"]
---

# Create a Retry Policy

`POST /retry-policies`

Create a new Retry Policy with the provided details

## Request body

- CreateRetryPolicyDTO
  - `title` string, required — Comment for the configuration
  - `steps` CreateRetryPolicyStepRetryPolicyDTO[], required — Recovery rules associated with the configuration
    - `position` number, required — Position of the rule. Rules are executed from lowest to highest position number.
    - `useInitialGateway` boolean — Whether to use the last successful gateway or a specific gateway profile. If false, gatewayProfileId must be provided.
    - `gatewayProfile` string — ID of the gateway profile to use. Required if useInitialGateway is false.
    - `priceReductionPercentage` number — Percentage to reduce the price by when retrying the payment.
    - `retryDelay` number, required — Number of days to wait from the last failed payment before retrying.

## Response `201`

OK

- RetryPolicyDTO
  - `createdAt` string, date-time, required — The date and time when the entity was created.
  - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
  - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
  - `id` string, required — The unique identifier of the retry policy
  - `title` string, required — Human-readable name for the retry policy
  - `isDefault` boolean, required — Whether this policy is the default retry policy applied when no specific policy is configured
  - `isEnabled` boolean — Whether payment retries are active for this policy
  - `steps` object[], required — The ordered list of retry steps that define the retry strategy
    - `createdAt` string, date-time, required — The date and time when the entity was created.
    - `updatedAt` string, date-time, nullable, required — The date and time when the entity was last updated.
    - `metadata` object, nullable — Metadata used by merchants to store additional information about the entity.
    - `retryPolicy` string, required — The unique identifier of the parent retry policy
    - `position` number, required — Position of this step in the retry sequence (lower = earlier)
    - `isEnabled` boolean — Whether this retry step is enabled
    - `useInitialGateway` boolean, required — Whether to use the same gateway that was used for the initial payment attempt
    - `gatewayProfile` string, nullable, required — The ID of the gateway profile to use for this retry step
    - `priceReductionPercentage` number, required — Percentage to reduce the original price by for this retry attempt (0-100)
    - `retryDelay` number, required — Delay in days before this retry step is executed

## Other responses

- `202` — The merchant is entitled but its environment is not provisioned yet. Provisioning has been kicked off (exactly once) and is in progress; retry the request — it succeeds once the environment is ready. Returned only for identity-token (dashboard) requests bound to a merchant, not for secret-key API calls; any such endpoint can return it while provisioning is underway.
- `400` — The request was rejected. `type` is `invalid_request_error` when the request itself is at fault — `errors` then lists every problem found, with field-attributable entries prefixed by the field’s path; `invalid_state_error` when the request was well-formed but the resource is not in a state that allows it; or `payment_error` when the payment was refused by the issuer or processor.
- `401` — No API key was supplied, or the key is not valid. `type` is `authentication_error`.
- `403` — The API key is valid but lacks the permission this operation requires. `type` is `permission_error`.
- `409` — `type` is `conflict_error`. The supplied `X-Idempotency-Key` was already used with a different request body (`code` is `idempotency_conflict`, and retrying will not help), or the resource is being modified by another in-flight request (`code` is `resource_locked`, and retrying with backoff will).
- `429` — Too many requests. The rate limit is applied per client across all operations. `type` is `rate_limit_error`.
- `500` — The request could not be completed because of an unexpected error. `type` is `api_error`.
- `503` — A dependency needed to authorize the request is temporarily unavailable — the auth service that verifies credentials, or the entitlement lookup behind it. `type` is `api_error`. It is raised before the operation runs, so the request had no effect, and unlike a plain 500 the condition is transient: retry with backoff.
- `504` — The request exceeded the processing time limit and was abandoned. `type` is `api_error` and `code` is `timeout` — unlike a plain 500 the request may still have taken effect, so retry with the same idempotency key rather than blindly.

## Changes

- **2026-09-02** `de9880e65aea` — 1 info
  - added the non-success response with the status `503`

[Change history](https://skmtc.dev/odus/apis/odus-orchestration-api/changes/retry-policies/post.md)

---

[API](https://skmtc.dev/odus/apis/odus-orchestration-api.md) · [All operations](https://skmtc.dev/odus/apis/odus-orchestration-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/odus/odus-orchestration-api/revisions/de9880e65aea/schema)