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 see | Where 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 available | The 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 403 | Look 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 connected | Request 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 anything | Almost 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 enquiries | Before 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 up | Check 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_data | That 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_indexed | You 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 unassociated | The 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 published | it is updated, not created again |
| the publish of a development | the parent is updated, and of the units only the missing ones are touched |
| a takedown of something that was already down | it 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.
state | what to do |
|---|---|
rejected | fix the object with the PUT and then retry: the block names the field |
blocked | do not retry: it is the state of the account and we resolve it |
synced without images | retry: 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 means | What to do | |
|---|---|---|
| the portal rejected | your data or your account: something is missing, something is extra, the listing does not exist yet | fix it and come back |
| we got no answer | we do not know whether it went through. The reason is portal_unreachable | retry, 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:
- 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.
- What you expected and what happened, in that order.
- The
clientRefand 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.
Related
- Best practices — the complete flows
- Checking — step 2, the most profitable one
- Publication — what each portal supports