BETA

When something does not work

The order below is not arbitrary: it goes from free to expensive, and from what you can see yourself to what we have to look at. The first two steps solve most cases and spend nothing from your client's allowance.

The order

1 · read the full error                 free — and it almost always says which step is missing
2 · check the object                    free — POST /properties/verify
3 · read what we have stored            free — GET /properties/{paId}
4 · ask the portal                      costs 1 call
5 · write to us                         with the reference from step 1

1 · The full error, not just the code

Our errors are written to say what to do, not just that something failed. Besides the code they carry a description and, where relevant, the name of the field or the portal.

The most important part: one of our errors tells you whether the problem is yours (something in what you sent) or from the previous step (the record is missing, the connection is missing). If it says the account needs connecting, it is not a permissions problem with your token.

2 · Check the object (free)

POST /properties/verify with the same object that failed. It tells you, portal by portal, what is missing. It asks the portal nothing, so it spends no allowance and does not depend on the portal being up.

It separates two things worth not mixing up:

  • What is missing in the object → that is within your control.
  • What is missing from the account (the plan, the branch) → that comes from the connection, not from the property.

3 · What we have stored (free)

GET /properties/{paId} shows you what we recorded: whether the property exists, which portals it has, and what happened on the last publish attempt.

It is the step that answers "did my call arrive?" without spending anything.

4 · Asking the portal (1 call)

GET …/publication/{portal} is the only thing that knows whether the listing is online right now and what its URL is.

Leave it for last: it is the only one that costs, and the three previous steps usually explain the problem without it.

The cases that come up most

What you seeWhere to start
"I published and I do not see the listing"The portal can take a while to show it. Step 4 tells you whether it already has it; if it says yes, that is the portal's publication timing, not an integration problem
"I published again right away and it was rejected"The portal processes one listing at a time: while it finishes the previous one, it does not accept the next. We tell you it is temporary, with how many seconds to wait — wait and retry, do not change anything. It happens more with large developments, where the portal works in deferred mode
"I unpublished it and it came back online"The takedown arrived while the portal was still processing the publication: it answered fine, and then the portal finished its pending work and published it again. Wait until it stops being processed and unpublish again. Happens with large developments, where the deferred window is minutes long
The plan I asked for is not availableThe publish response tells you which ones your client does have. If that is not what you expected, refresh the plans against the portal: one may have been used up or expired
A 403Look at which scope it says is missing. If it names a portal, your token is not enabled for that portal — which is different from not being able to read or write
It says the account is not connectedRequest the client's record (free) and look at the state of their connections. Your client may have disconnected it on the portal's side
🔴 "It was working, and suddenly EVERYTHING gets rejected" — publishing, taking down, checking and reading plans, all at once, without you having touched anythingAlmost always it is that your client's account was reconnected from somewhere else. Some portals allow a single connection per agency —Zonaprop is one—, so the latest one switches off the previous. It is fixed by connecting it through the API again: Connect with a link. The details are in Zonaprop
An empty list of enquiriesBefore assuming there are none, check which mode that portal supports: it may be that enquiries there are not requested but arrive on their own
It says the zone does not exist (zone2, rule: not_found)The value carries the 4-segment code we looked up. Compare it against the zone catalogue: either the zone changed, or your equivalence table went stale. The hierarchy counts too: a correct zone2 hanging off a different zone1 does not exist
An attribute did not get published (attributes[n].id, rule: unknown)That id does not exist in the catalogue of that country — and the catalogues differ between countries. Request the catalogue with the property's country and compare
Something you sent does not show upCheck it (step 2): if the portal does not support that field, we tell you there instead of discarding it silently
"I assigned points and the position did not change"Look at the balance, not the position. The portal takes a while to recompute: if the balance went down, it was applied. The position updates later — and the simulation's number is the estimate, not a promise. Paying for position
The simulation comes back empty with segment_insufficient_dataThat property's market is too small for the portal to have statistics. There are no numbers to give you — it is not a failure of ours and not something to retry
The simulation comes back empty with not_indexedYou published very recently. The balance and the position come back anyway; wait and ask again
We got no answer from the portal (portal_unreachable)It does not mean your data is wrong: it means we do not know what happened. The write may or may not have gone through. Retry — repeating the same call does not duplicate anything (below)
Part of a development was left unassociatedThe development stays published and whatever failed comes back per unit with its reason. Repeat the development publish: only what is missing is redone

Retrying is safe, and only redoes what is missing

This holds for every portal, it is not specific to any one: repeating a publication operation does not duplicate listings or redo work already done. Before writing, we compare against what the portal has and act on the difference.

If you repeat…What happens
the publish of a listing that is already publishedit is updated, not created again
the publish of a developmentthe parent is updated, and of the units only the missing ones are touched
a takedown of something that was already downit answers fine anyway. You do not have to keep count

The creation in Mapaprop has its own retry

If your token was issued from a Mapaprop account, the property is created there by itself. When that is stopped, the mapaprop block of the GET says why and POST /properties/{paId}/mapaprop tries again.

statewhat to do
rejectedfix the object with the PUT and then retry: the block names the field
blockeddo not retry: it is the state of the account and we resolve it
synced without imagesretry: it sends only the accessories, it does not create the property again

⚠️ What it does cost is your client's allowance: every call to the portal is billed to them, so retrying in a loop is not free even though it is safe. If an error told you to wait, wait that long.

🔴 And the distinction that confuses the most: the portal rejecting your data and us not getting an answer are not the same thing, even though both arrive as a failure of that unit.

What it meansWhat to do
the portal rejectedyour data or your account: something is missing, something is extra, the listing does not exist yetfix it and come back
we got no answerwe do not know whether it went through. The reason is portal_unreachableretry, without changing anything

What to rule out before writing to us

  • Did the error say it was TEMPORARY? If we told you to wait and retry —and how many seconds—, try that first: some rejections resolve on their own and there is nothing to fix.
  • Did you check the object? It is free and it answers most cases.
  • Does the error name an earlier step (record, connection)? Then the problem is not where you are looking.
  • Are you using the identifier we returned, and not one of yours, where the route asks for ours?
  • Does the portal support that? Not all of them support everything, and what is not supported we say without spending allowance.

5 · Write to us

Support goes up the chain: your client writes to you, and you write to us. Your client does not need to —and should not— write to the portal about anything to do with the integration.

The reason is structural, not a preference of ours: the link with the portal is Mapaprop's. Your system does not appear as an integration on the portal's side, so a claim presented in its name lands in a conversation nobody over there can place. You write to us and we channel it.

⚠️ This does not change what your client contracts. Their account, their plan and what they pay stay directly with the portal — that never went through us. What goes up the chain is the integration problem, not the commercial relationship.

dev@mapaprop.com. What speeds up the answer the most:

  1. The reference that came with the error. With that we find your exact call in our records — it is the difference between looking at the case and asking you to reproduce it.
  2. What you expected and what happened, in that order.
  3. The clientRef and the property's identifier.

Do not send us your token or your client's credential. We do not need them to diagnose, and if you sent them by mistake, tell us so we can help you rotate them.