Publishing errors

These errors happen when something's wrong with the publication request (POST, PUT, DELETE, Activate, or Deactivate). Below you can find the most common situations and their respective solutions.

Posting a duplicate advert

To avoid content duplication we automatically detect situations where you post an advert that contains that same:

custom_fields.id
category_urn
as an existing advert. In these cases, we'll simply reuse that record and return the same UUID back to you.

{
    "transaction_id": "b251fcb2-98a9-41a2-99dc-0457cce44c24",
    "message": "Resource with custom_fields.id 11 and category_urn urn:concept:investments already exists. To update this resource use a PUT operation instead."
}

Solution

If you received an error message alerting you that the advert already exists, use a PUT operation to do any updates on the advert, instead of using a POST.

Duplicate attributes

If you post adverts with duplicate attributes you'll get an error as shown below:

{
    "transaction_id": "931fefdd-bc7a-4c5a-a70a-0db089b52ce3",
    "message": "Requested body doesn't comply with the service requirements",
    "errors": [
        {
            "field": "urn:concept:net-area-m2",
            "message": "The attribute urn:concept:net-area-m2 is present more than once"
        }
    ]
}

Solution

Make sure to check out if there are no duplicated attributes in your request. The duplicate field(s) will be displayed in the error message to help you debug. Remove it and send the request again.

Requested body doesn't comply with the service requirements

HTTP code: 400 Bad Request
You can get this error when the ad you're trying to publish doesn't comply with the validation rules. For example, if you forget to include the contact parameter, you'll get an error such as:

{
    "transaction_id": "556ecc20-3f2e-11e8-a691-55a1dd521900",
    "message": "Requested body doesn't comply with the service requirements",
    "errors": [
        {
            "field": "contact",
            "message": "contact parameter is required"
        }
    ]
}

Solution

Make sure to check out the Advert validation rules page and confirm that your ad complies with all the rules described there.

Cannot publish an ad because personal contact info is missing

When you try to activate an advert and you'll get a notification in your webhook with the following error for field: contact.person:

{
  "data": {
    "data": {
      "detail": "Adding the ad failed.",
      "title": "AdvertsPostingException",
      "validation": [
        {
          "detail": "Deve indicar um contacto pessoal",
          "field": "contact.person",
          "title": "Error"
        }
      ]
    },
    "destination": "https://myawesomeapp.com/webhooks",
    "error_message": "Adding the ad failed.",
    "event_timestamp": 1580844552429,
    "event_type": "advert_posted_error",
    "flow": "publish_advert",
    "object_id": "7cadf3e8-fe2d-4b58-9992-02a0318d7714",
    "timestamp": 1580844552429,
    "transaction_id": "0641f05a-91b6-11e8-9369-75b35a5b6605"
  },

This error is because the client has authenticated with a private account instead of using a professional one (agency, developer, promoter...).

Solution

If one of your (or your clients' ads) is getting the error because personal contact is missing, you must contact your client and ask them to authenticate with a professional account. After that, help them to re-export the advert(s).

Cannot publish an ad because the contact image is getting an error

When you try to activate an advert and you'll get a notification in your webhook with the following error:

"data": {
    "data": {
      "detail": "Adding the ad failed.",
      "title": "AdvertsPostingException",
      "validation": [
        {
          "detail": "Ficheiro não existe (slot #1)",
          "field": "contact.image",
          "title": "Error"
        }
      ]
    },
    "destination": "https://myawesomeapp.com/webhooks",
    "error_message": "Adding the ad failed.",
    "event_timestamp": 1578566260785,
    "event_type": "advert_posted_error",
    "flow": "publish_advert",
    "object_id": "7cadf3e8-fe2d-4b58-9992-02a0318d7714",
    "timestamp": 1578566260785,
    "transaction_id": "f267c4e6-283b-464c-a99a-089fc691800f"
  },

Solution

If one of your (or your clients' ads) is getting the error because of the contact image, you must validate if contact.photo has the right validations. Refer to contact.photo in Advert validation rules. After that, help them to re-export the advert(s).

Cannot publish an ad because the operation failed

When you try to post/update an advert, and you got a webhook describing that the operation fails, but without any specific value (e.g: mandatory fields are missing). As the example bellow:

"data": {
    "data": {
      "activated_at": null,
      "code": "<ad status - if the ad alredy exists>",",
      "created_at": "2021-05-19T19:20:21.620Z",
      "detail": "Update action failed",
      "moderation": {
        "description": null,
        "reason": null
      },
      "modified_at": "2021-05-19T19:20:21.620Z",
      "recorded_at": null,
      "title": "Operation failed",
      "ttl": "2021-06-18T16:18:08.000+0000",
      "url": "<ad url - if the ad alredy exists>",
      "validation": null
    },
    "destination": "https://myawesomeapp.com/webhooks",
    "error_message": "Update action failed",
    "event_timestamp": 1621452021864,
    "event_type": "advert_posted_error",
    "flow": "publish_advert",
    "object_id": "d17bce24-ff40-4d07-a710-54e36a342f6e",
    "timestamp": 1621452021864,
    "transaction_id": "3bb6a94f-a3e7-4a83-9e37-69fbd1b9d3a6"
  },

Solution

When you got an advert_xxxx_error (xxxx, can be posted, put, deleted, deactivated or activated), the same operation request will always need to be sent again. Check here the next available operations for all publishing requests.
So, in this case, re-export the advert(s) automatically in the next sync. No need to wait for the client(s) to do any update on the advert, only processing it automatically since something failed on our side (e.g: time out).

Unauthorized request

When you try to do any operation with a valid token (with a valid expiration date) and you'll get a notification in your webhook with the following error:

"error": {
    "detail": "Unauthorized request",
    "title": "MercuryForbiddenException",
    "validation": null
  },

That means that the token expiration date was not yet achieved, however, the client revokes the APP. So now, you don't have access to their adverts to do any operation.

Solution

The client needs to authorize again the APP. After that, an export in volume is needed to have all adverts correctly sync. First, get all adverts from the client account, using Get advert metadata, then compare his status with what you have on your side. For last, send all operations that are needed to sync and align information between both platforms.

Updating the ID field error

The field custom_fields.id cannot be updated. If you try to send a PUT operation for a published advert and change the value of this field, you'll get an error as shown below:

{
    "transaction_id": "1eccb6a5-f7d4-11e8-86c5-1be52bedc6d3",
    "message": "Cannot change custom_fields.id field."
}

Solution

If one of your (or your clients' ads) is getting this error you need to change the custom_fields.id to the one sent previously during the POST operation. In case the custom field changed on your side and you need to start using this new one, you should send us a Delete Operation and them publish again the same advert but with the new custom_fields.id. This last operation will create another advert.

Cannot update or activate ad because not a valid key

When you try to activate an advert or editing and deleting adverts an advert, and you get a notification in your webhook with the following error:

{
  "transaction_id": "ed518e0a-7826-4ac0-89bc-212ce0af1f2a",
  "message": "'218993621b1e255811c0c398b6071fd74b89c977' not a valid key=value pair (missing equal-sign) in Authorization header: 'Bearer 218993621b1e255811c0c398b6071fd74b89c977'."
}

Solution

That message is because the request does not have the correct format.

Check the following scenarios:

You are trying to POST an ad and you have included in the request a UUID received from a previous request that when error.
To solve, remove the UUID of the endpoint and submit again the request as a new POST.
You are trying to edit an ad, however, the request made was a POST.
To solve, send us a PUT operation.

Any action (post, update, delete, deactivate, or activate) will always return a similar error like the one above if the endpoint set in the request does not fulfill the correct structure (as examples above). So make sure that you are sending or not the advert UUID on the endpoint taking into consideration the request you have the intention to send us.

Cannot update or activate ad because it was moderated

When you try to activate an advert that was previously moderated for some reason, you'll get a notification in your webhook with the following error:

{
    "data": {
        "detail": "Anúncios removidos pela equipa do Imovirtual. Não pode editar este anúncio.",
        "title": "BadRequestException",
        "validation": null
    },
    "destination": "https://myawesomeapp.com/webhooks",
    "error_message": "Anúncios removidos pela equipa do Imovirtual. Não pode editar este anúncio.",
    "event_timestamp": 1532707163221,
    "event_type": "advert_activated_error",
    "flow": "publish_advert",
    "object_id": "7cadf3e8-fe2d-4b58-9992-02a0318d7714",
    "signature": "cf8fabc5d5369dcf1a93be35e63fd5439e067673",
    "timestamp": 1532707163221,
    "transaction_id": "0641f05a-91b6-11e8-9369-75b35a5b6605"
}

Solution

If one of your (or your clients' ads) is moderated, the application user must contact their account manager directly to correct the advert and unblock the situation to be republished. For example, any action (update or activate, for example) will always return a similar error to the one above.

Cannot activate ad because it was activated

When you try to activate an advert that was previously activated for some reason, you'll get a notification in your webhook with the following error:

{
  "destination": "https://myawesomeapp.com/webhooks",
  "timestamp": 1695120894807,
  "event_timestamp": 1695120894807,
  "transaction_id": "16704fc4-39bb-4bff-9abb-f30cc603429d",
  "object_id": "958b2f80-3d3b-48e4-bce9-ed88bc15316c",
  "flow": "publish_advert",
  "error_message": "Este anúncio já se encontra ativo",
  "data": {
    "activated_at": "2023-09-19T10:54:35.000Z",
    "recorded_at": "2023-09-19T10:54:50.051Z",
    "code": "active",
    "moderation": {
      "description": null,
      "reason": null
    },
    "created_at": "2023-09-19T10:53:08.000Z",
    "detail": "Este anúncio já se encontra ativo",
    "visible_in_profile": true,
    "title": "BadRequestException",
    "modified_at": "2023-09-19T10:54:49.000Z",
    "ttl": "2023-10-19T10:54:26.000Z",
    "validation": null,
    "url": "https://www.imovirtual.com/pt/anuncio/advert.html"
  },
  "event_type": "advert_activated_error"
}

Solution

Actions performed in the CRM should be based on the information returned by Advert Notifications. If you activate an advert, you will receive a webhook afterwards with information about the result of the processing. The webhook contains information about the current status of the advert (for example: "event_type": "advert_activated_success", code: active, "visible_in_profile": true). When you receive such a notification, you should remember this status for your advert so that re-activation is not possible.

Cannot activate ad because it was deleted

When you try to activate an advert that was previously deleted for some reason, you'll get a notification in your webhook with the following error:

{
  "destination": "https://myawesomeapp.com/webhooks",
  "timestamp": 1695121650385,
  "event_timestamp": 1695121650385,
  "transaction_id": "fadf1434-63c1-45ec-8e2c-c1b5488ffd70",
  "object_id": "958b2f80-3d3b-48e4-bce9-ed88bc15316c",
  "flow": "publish_advert",
  "error_message": "Anúncio removido",
  "data": {
    "activated_at": "2023-09-19T10:54:35.000Z",
    "recorded_at": "2023-09-19T11:07:06.734Z",
    "code": "removed_by_user",
    "moderation": {
      "description": null,
      "reason": null
    },
    "created_at": "2023-09-19T10:53:08.000Z",
    "detail": "Anúncio removido",
    "visible_in_profile": false,
    "title": "BadRequestException",
    "modified_at": "2023-09-19T11:07:06.000Z",
    "ttl": "2023-09-19T11:07:06.000Z",
    "validation": null,
    "url": "https://www.imovirtual.com/pt/anuncio/advert.html"
  },
  "event_type": "advert_activated_error"
}

Solution

Actions performed in the CRM should be based on the information returned by Advert Notifications. If you delete an advert, you will receive a webhook afterwards with information about the result of the processing. The webhook contains information about the current status of the advert (for example: "event_type": "advert_deleted_success", code: removed_by_user, "visible_in_profile": false). When you receive such a notification, you should remember this status for your advert so that re-activation is not possible.

Cannot deactivate ad because it was deactivated

When you try to deactivate an advert that was previously deactivated for some reason, you'll get a notification in your webhook with the following error:

{
  "destination": "https://myawesomeapp.com/webhooks",
  "timestamp": 1695122093654,
  "event_timestamp": 1695122093654,
  "transaction_id": "cf099f7c-3f7f-4ac5-8633-faf85c541ad0",
  "object_id": "958b2f80-3d3b-48e4-bce9-ed88bc15316c",
  "flow": "publish_advert",
  "error_message": "O anúncio tem que estar ativo",
  "data": {
    "activated_at": "2023-09-19T11:14:38.000Z",
    "recorded_at": "2023-09-19T11:14:48.660Z",
    "code": "removed_by_user",
    "moderation": {
      "description": null,
      "reason": null
    },
    "created_at": "2023-09-19T10:53:08.000Z",
    "detail": "O anúncio tem que estar ativo",
    "visible_in_profile": true,
    "title": "BadRequestException",
    "modified_at": "2023-09-19T11:14:48.000Z",
    "ttl": "2023-09-19T11:07:06.000Z",
    "validation": null,
    "url": "https://www.imovirtual.com/pt/anuncio/advert.html"
  },
  "event_type": "advert_deactivated_error"
}

Solution

Actions performed in the CRM should be based on the information returned by Advert Notifications. If you deactivate an advert, you will receive a webhook afterwards with information about the result of the processing. The webhook contains information about the current status of the advert (for example: "event_type": "advert_deactivated_success", code: removed_by_user, "visible_in_profile": true). When you receive such a notification, you should remember this status for your advert so that second deactivation is not possible.

Cannot deactivate ad because it was deleted

When you try to deactivate an advert that was previously deactivated for some reason, you'll get a notification in your webhook with the following error:

{
  "destination": "https://myawesomeapp.com/webhooks",
  "timestamp": 1695122250415,
  "event_timestamp": 1695122250415,
  "transaction_id": "57fadd76-f026-487b-ad27-339617fbc5b1",
  "object_id": "958b2f80-3d3b-48e4-bce9-ed88bc15316c",
  "flow": "publish_advert",
  "error_message": "O anúncio tem que estar ativo",
  "data": {
    "activated_at": "2023-09-19T11:14:38.000Z",
    "recorded_at": "2023-09-19T11:17:22.172Z",
    "code": "removed_by_user",
    "moderation": {
      "description": null,
      "reason": null
    },
    "created_at": "2023-09-19T10:53:08.000Z",
    "detail": "O anúncio tem que estar ativo",
    "visible_in_profile": false,
    "title": "BadRequestException",
    "modified_at": "2023-09-19T11:17:22.000Z",
    "ttl": "2023-09-19T11:17:21.000Z",
    "validation": null,
    "url": "https://www.imovirtual.com/pt/anuncio/advert.html"
  },
  "event_type": "advert_deactivated_error"
}

Solution

Cannot update ad because it was deleted

When you try to update an advert that was previously deleted for some reason, you'll get a notification in your webhook with the following error:

{
  "destination": "https://myawesomeapp.com/webhooks",
  "timestamp": 1695202468228,
  "event_timestamp": 1695202468228,
  "transaction_id": "dddb0de3-039c-4427-9412-3beb5a6932d9",
  "object_id": "1ef37504-674d-4289-a41f-660cfce7dedd",
  "flow": "publish_advert",
  "error_message": "Editing the ad failed.",
  "data": {
    "activated_at": "2023-09-20T09:33:52.000Z",
    "recorded_at": "2023-09-20T09:34:14.964Z",
    "code": "removed_by_user",
    "moderation": {
      "description": null,
      "reason": null
    },
    "created_at": "2023-09-20T09:33:50.000Z",
    "detail": "Editing the ad failed.",
    "visible_in_profile": false,
    "title": "AdvertsPostingException",
    "modified_at": "2023-09-20T09:34:14.000Z",
    "ttl": "2023-09-20T09:34:14.000Z",
    "validation": [
      {
        "detail": "Anúncio removido",
        "field": "ad",
        "title": "Error"
      }
    ],
    "url": "https://www.imovirtual.com/pt/anuncio/advert.html"
  },
  "event_type": "advert_put_error"
}

Solution

Got a server error (5xx)

If you got an error with the following structure: "Got a server error (5xx) from Target API (hard)...", that means that the request has a duplicated attribute. In this case, we cannot consider it as a duplicated attribute because both have different values. So, our platform is struggling to get which is the right value to fill — more about duplicated values (same attribute and same value) here.
So you'll get an error as shown below:

{
    "data": {
      "detail": "Got a server error (5xx) from Target API (hard), will not try again because i reached the maximum number of receives or the retries extended the visibility time past the max allowed by SQS.",
      "title": "TargetServerErrorHardException",
      "validation": null
    },
    "destination": "https://myawesomeapp.com/webhooks",
    "error_message": "Got a server error (5xx) from Target API (hard), will not try again because i reached the maximum number of receives or the retries extended the visibility time past the max allowed by SQS.",
    "event_timestamp": 1622909202148,
    "event_type": "advert_posted_error",
    "flow": "publish_advert",
    "object_id": "c7a5b6d0-ea89-4874-b1c0-63bebcba92a3",
    "timestamp": 1622909202148,
    "transaction_id": "5159b2be-d26c-461d-bd4f-2eb023050915"
  },

Solution

Check for duplicated attributes, and implement a validation to make sure no attributes are being sent twice in the same post request. Check the following piece of a request payload, as an example:

{
          "urn": "urn:concept:net-area-m2",
          "value": "4700"
        },
        {
          "urn": "urn:concept:gross-area-m2",
          "value": "2890"
        },
        {
          "urn": "urn:concept:gross-area-m2",
          "value": "4700"
        },