Troubleshooting
Errors use the standard envelope { "status": "error", "message": "…" }. The HTTP status code tells you the category; the message is human-readable and is meant for logs and debugging rather than for display to end users.
Status codes
Section titled “Status codes”| Status | Meaning | Typical messages |
|---|---|---|
400 |
A path/query parameter or the request body failed validation. | id must be a positive integer, client.email or client.mobile_number is required |
401 |
The key is missing or invalid. “Invalid” covers unknown, revoked and deleted keys. | missing api key, invalid api key, api key author is gone |
403 |
The key is valid but not allowed: its domain list does not match the request, or the agency has no approved licence. | origin is not allowed for this api key, agency license is required: upload a company license and wait for its approval |
404 |
No record exists with this ID — or it belongs to a draft/deleted project or to a developer the agency has no approved contract with. | unit not found |
500 |
An unexpected error. The cause is logged server-side; a generic message is returned. | internal server error, offer status catalogue is empty |
400 errors are caused by the request — fix it before retrying. 401 and 403 are configuration problems — retrying does not help. 500 can be retried with backoff, except on POST /units/{id}/applications: applications are not idempotent, and retrying a request that actually succeeded creates a duplicate opportunity and offer.
Error → Fix
Section titled “Error → Fix”missing api key — 401
Section titled “missing api key — 401”Cause: the request carries neither an X-API-Key header nor an Authorization header with the key.
Fix: send the key on every request, including from server code and proxies — see Sending the key. With Authorization, use the Bearer scheme or a bare value: any other scheme is ignored.
invalid api key — 401
Section titled “invalid api key — 401”Cause: the key is unknown, revoked or deleted. Typos, truncated keys and unset build variables (sent as the string undefined) land here too.
Fix: check that the full key reaches the request, then check its status in the API keys section of estate.azizdubai.com. A key is shown only once at creation, so if it is lost or revoked, issue a new one and replace it everywhere it is used.
api key author is gone — 401
Section titled “api key author is gone — 401”Cause: returned by POST /units/{id}/applications when the key’s company or the user who issued the key has been removed. Applications are recorded on behalf of that user, so they cannot be created without one.
Fix: have an active user with the API keys permission issue a new key, and replace the old one.
origin is not allowed for this api key — 403
Section titled “origin is not allowed for this api key — 403”Cause: the key has a domain list, and the host of the request’s Origin header (or Referer, if Origin is absent) does not exactly match any listed domain. Requests that carry neither header — server code, cron jobs, curl, Postman — are rejected as well.
Fix:
- In the browser, add the exact host to the key’s domain list. Subdomains are not covered: list
example.comandwww.example.comseparately. - For local development, use a separate key — a key restricted to production domains rejects
localhost. - On a server, use a separate key without a domain list. See Domain restriction.
agency license is required: upload a company license and wait for its approval — 403
Section titled “agency license is required: upload a company license and wait for its approval — 403”Cause: the agency that owns the key has no approved licence. Every operation answers this until it does.
Fix: upload the company licence on estate.azizdubai.com and wait for its approval. No change to the key is needed — it starts working once the licence is approved.
id must be a positive integer — 400
Section titled “id must be a positive integer — 400”Cause: the {id} in /projects/{id}, /projects/{id}/contacts, /units/{id} or /units/{id}/applications is not a positive integer — often undefined or null from a missing route parameter.
Fix: validate the ID before calling the API, and show “not found” without a request when it is missing.
client.email or client.mobile_number is required — 400
Section titled “client.email or client.mobile_number is required — 400”Cause: the application body has no contact channel.
Fix: require at least one of the two fields in your form before submitting. Other 400 responses from POST /units/{id}/applications cover a body that is not JSON or exceeds 64 KiB, a missing first name, an unknown reference ID, an inverted budget range, or a value over its maximum length — see Submitting applications. Show the message next to the form.
unit not found and other 404s
Section titled “unit not found and other 404s”Cause: no record exists with this ID, its project is a draft or has been deleted, or it belongs to a developer your agency has no approved contract with. All three look the same.
Fix: treat it as “no longer available” in your UI and drop the item from any cache. If a whole developer’s catalogue disappears, check that the agency’s contract with that developer is still approved. See Visible developers.
internal server error — 500
Section titled “internal server error — 500”Cause: an unexpected error on the Aziz side. The cause is logged there.
Fix: retry GET requests with exponential backoff. Do not retry POST /units/{id}/applications automatically. If it persists, report it to Aziz with the time of the request and the endpoint.
offer status catalogue is empty — 500
Section titled “offer status catalogue is empty — 500”Cause: returned by POST /units/{id}/applications when offer status reference data is not configured on the server.
Fix: nothing to change on your side, and retrying does not help. Report it to Aziz.