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].

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.
A valid OAuth 2.0 access token. For more information, access 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] 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.