---
title: "POST | Retry an IAM job by [id]"
slug: "api-v2-post-retry-an-iam-job"
updated: 2026-11-03T14:57:58Z
published: 2026-11-03T14:57:58Z
canonical: "docs.senhasegura.io/api-v2-post-retry-an-iam-job"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# POST | Retry an IAM job by [id]

## Description

Run a failed IAM background job again in the Segura™ platform. The job is queued once more on the same record: its identification code stays the same, `retry_count` increases by one, and the previous result and error are cleared.

Only a job in the `failed` state can be retried. To check the state first, access [GET | List an IAM job by [id]](/v4-2/docs/api-v2-get-list-an-iam-job).

---

## Prerequisites

- An application with the **Users** authorization granted by the administrator in A2A, and its resource permission set to **Read and write**. For more information, access [How to manage authorizations in A2A](/v4-2/docs/how-to-manage-authorizations-in-a2a).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).
- The job must be in the `failed` state and must have been started by the same application or user making this request.

---

## Request

`POST` `/api/v2/iam/jobs/{id}/retry`

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identification code of the job, in UUID format. **Note:** this value is returned by the endpoint that started the job. |

The request takes no body.

---

### Example request

`POST` `{{url}}/api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8/retry`

---

## Response

```
HTTP/1.1 202 Accepted
Location: /api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8
```

The `Location` header holds the path of the job, which is the same job that was retried.

### Example response body

```
{
    "data": {
        "job": {
            "id": "019e0a01-b7b8-7062-82dd-43a8aa0ed6f8",
            "type": "ldap.test_connection",
            "state": "queued",
            "retry_count": 1,
            "created_at": "2026-05-08 23:52:25",
            "started_at": null,
            "finished_at": null
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8" }
    }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The accepted request. |
| `data.job` | object | Job that was queued again. |
| `data.job.id` | string | Unique identification code of the job, unchanged by the retry. |
| `data.job.type` | string | Type of job. |
| `data.job.state` | string | State of the job. A retried job returns `queued`. |
| `data.job.retry_count` | integer | Number of times the job was retried, increased by one for this request. |
| `data.job.created_at` | datetime | Date and time the job was first created. The retry does not change it. |
| `data.job.started_at` | datetime | Reset to `null` until a worker picks the job up again. |
| `data.job.finished_at` | datetime | Reset to `null` until the job ends. |
| `meta` | object | Response metadata. |
| `meta.links` | object | Navigation links for the job. |
| `meta.links.self` | string | Path of the job. |

              Info

              

The retry reuses the job record, so the outcome of the earlier attempt is lost. Read the `error` object with [GET | List an IAM job by [id]](/v4-2/docs/api-v2-get-list-an-iam-job) before retrying if the earlier failure still matters.

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `401` | `api.auth.unauthorized` | The access token is missing or has expired. | Request a new access token. |
| `404` | `api.resource.not_found` | The job does not exist, is older than 24 hours, or was started by a different user through a different application. | Check the identification code, and send the request with the application or the user that started the job. |
| `409` | `api.job.invalid_transition` | The job is not in the `failed` state. | Read the job and retry it only after it fails. |
| `429` | `api.rate_limit.exceeded` | The request rate limit was exceeded. | Reduce the request rate and try again. |

The platform also answers `503 Service Unavailable` (`api.service.unavailable`) when the background worker queue is full and the job cannot be queued. The response body carries the number of seconds to wait before resending the request in `details.retry_after`. From version 4.2.15, the platform also sends the same value in the `Retry-After` header.

For authentication error messages and the `403` versus `404` policy, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).