Tasks Management

How asynchronous tasks on domain names work

Last updated 5th May 2022

To follow this guide, make sure you are connected to OVHcloud API. You may find more information on the API introduction page if needed.

Table of Contents

We remind you that the given API routes links lead to European API. Do not forget to replace https://eu.api.ovh.com with https://ca.api.ovh.com in API URLs to use it with your identifier.

Task management

Most of the actions carried out on domain names result in modifications on the registrar's side (OVHcloud), as well as on the registry. For the sake of robustness and performance, they are launched asynchronously.

To allow tracking of these asynchronous changes, actions are abstracted as tasks. When an asynchronous action is launched a task is created and allows to retrieve a status, to modify some data in case of error or to restart actions after a failure.

Historically, OVHcloud tasks are handled via two distinct API paths:

  1. /me/task/domain and its children
  2. /domain/{serviceName}/task and its children

The available routes handle the same tasks but offer different actions.

Tasks workflow

The nominal life cycle of a task is the following:

  • todo: the task has been created but is not being processed. Most tasks (DomainCreate, DomainRenew, etc.) are executed within a minute, and finalized within 5 to 10 minutes.
  • doing: the task is being processed. This phase usually lasts a few seconds.
  • done: the task has been successfully processed. This is a final status.

The following statuses can also occur in non-nominal cases:

  • cancelled: the task has been cancelled, either by the customer or by OVHcloud. This is a final status.
  • error: an error occurred during the execution of the task. Two cases are possible:
    1. An information provided by the customer is invalid or missing: in this case you will have the possibility to correct the problematic data and to restart the task.
    2. A problem has occurred on OVHcloud's side: in this case you will not be able to restart the task yourself. The task will be restarted periodically in an automatic way, but you will have to open a support request if the problem persists.

View pending tasks

To list your tasks, you can use the following API:

Parameter Mandatory Description
domain no Filter tasks related to this domain name
function no Type of tasks to retrieve
status no Status of tasks to retrieve

This API call will return the list of task IDs corresponding to your filters.

To retrieve the details related to a particular task, you can use the following API:

The most interesting fields in the answer are the following:

  • status: corresponds to the statuses presented in the previous section.
  • comment: contains detailed information about the status of the task. In particular, if the task is in error status, this field will contain a message to help you fix the problem.
  • canRelaunch: indicates whether it is possible for you to relaunch a task. This will be useful if the task is in error status.
  • todoDate: the approximate date and time when the task should be executed next. This only applies if the task is in todo status. It is possible to make this date closer using the POST /me/task/{id}/accelerate API, but this is rarely necessary.

Fix and relaunch a task in error

If your task is in error status and the canRelaunch field indicates that it can be restarted, you will probably have to correct some data. General correction information will be given in the comment field.

Let's take an example regarding a creation task (DomainCreate) of a .fr domain name in error status:

  "id": 1000,
  "function": "DomainCreate",
  "domain": "example.fr",
  "status": "error",
  "comment": "You have to explain in a few words how you'd like to use this domain name (AFNIC will use it to decide if you can register this domain)",
  "creationDate": "2022-01-01T12:00:00+01:00",
  "todoDate": "2022-01-01T13:00:00+01:00",
  "lastUpdate": "2022-01-01T12:40:00+01:00",
  "doneDate": null,
  "canAccelerate": false,
  "canRelaunch": true,
  "canCancel": false

The commentary explains that Afnic (registry of domain names in .fr) asks for a justification for the use of this domain name. In practice this can happen for .fr domain names matching the name of a city. The canRelaunch field indicates that the client has the possibility to relaunch this task, and thus implicitly to correct it.

To correct it, it is possible to list the fields to be modified using the following API:

In our example, it will only return a single field:


You can list more information about how to fill this field and its current value using the API:

  "key": "legitimacyAfnic",
  "description": "Update legitimacyAfnic with valid content",
  "type": "string",
  "value": null,
  "acceptedValues": null,
  "readOnly": false,
  "minimumSize": null,
  "maximumSize": null,
  "fields": null,
  "template": null,
  "acceptedFormats": null

To modify the legitimacyAfnic field, you will have to use the following API by entering its new value:

curl -XPUT /me/task/domain/example.fr/argument/legitimacyAfnic -d '{
  "value": "I am the mayor of the city Example."

Once the value is modified, you can, if you wish, reuse the API:

to verify that it has been taken into account.

Finally, all that remains is to relaunch the task via the API:

The task should be executed in the next few minutes and end correctly.

Task types

There are many different types of tasks (more than thirty), all with their own specificities. As a customer, you will rarely have to intervene on these. However, the most common ones are the following:

  • DomainCreate: creation of a domain name. Errors will generally be related to eligibility requirements, especially in the case of ccTLDs.
  • DomainIncomingTransfer, DomainAfterMarket: transfer of a domain name from another registrar or from an aftermarket. Errors will generally be related to the auth code allowing the validation of the transfer.
  • DomainTrade: change of owner contact. Errors will usually be related to eligibility incompatibilities on the receiving contact.
  • DomainContactUpdate: modification of contact information. Errors will generally be related to semantically invalid information, formatting errors or eligibility incompatibilities.
  • DomainDnsUpdate: changes regarding DNS configuration. Errors will generally be related to invalid DNS servers, or glue record configuration.
  • DomainDsUpdate: changes regarding DNSSEC keys. Errors will generally be related synchronizations issues between our system and the registry.

Did you find this guide useful?

Please feel free to give any suggestions in order to improve this documentation.

Whether your feedback is about images, content, or structure, please share it, so that we can improve it together.

Your support requests will not be processed via this form. To do this, please use the "Create a ticket" form.

Thank you. Your feedback has been received.

These guides might also interest you...

OVHcloud Community

Access your community space. Ask questions, search for information, post content, and interact with other OVHcloud Community members.

Discuss with the OVHcloud community