API error codes: what each code means
Every code the REST API returns in the member code of a problem, with its HTTP status and meaning. Generated from the contract.
Last updated:
Every code /v1 returns stands here with its status and meaning. A problem from the REST API names its code in code and links to the row of the code here with type. The code is an identifier for a branch in your program, not a sentence for a person. There is exactly one per meaning. Branch on the code, never on the HTTP status alone, and treat a code you do not know by its status. The format is described under Errors. The codes of the app and of the MCP servers do not apply to /v1; they are on the page App and MCP error codes.
| Code | Status | Meaning |
|---|---|---|
address_already_exists | 409 | A listing with this address and unit already exists in the office; the answer names it. Change it with PATCH or PUT, or send a data.location.unit that tells the two apart. |
address_missing | 409 | The person who inquired cannot be reached through Athaus: no account and no email address. |
api_version_unsupported | 400 | The header Athaus-Version names a version that does not exist. Send v1 or omit the header. |
automation_disabled | 409 | The office has switched this kind of message off in its automation. Nothing is prepared. |
503 | The payment service is not responding. Try again later. | |
brokerage_agreement_active | 409 | A brokerage agreement for the listing is still running, so it cannot be deleted. |
email_already_exists | 409 | The office already has a contact with this email address. |
email_consent_missing | 409 | The contact has not consented to email, so this message cannot go out. |
email_opted_out | 409 | The contact has objected to email, so this message cannot go out. |
forbidden | 403 | The key is valid, but it is not allowed to do this. |
idempotency_key_in_use | 409 | The first request with this Idempotency-Key is still running. Wait for Retry-After and send the same request again. |
idempotency_key_missing | 400 | The operation needs the header Idempotency-Key, and the request has none. |
idempotency_key_reused | 422 | The Idempotency-Key was already used with a different request body. Use a new key for a new request. |
idempotency_outcome_unknown | 409 | The first request with this key ended in the middle of its work, so nobody knows whether it wrote anything. Look at what exists, then retry with a new key. |
insufficient_permissions | 403 | The key lacks the scope, or the level on the resource, that the operation needs. |
internal_error | 500 | An error on our side. Quote the Request-Id to support. |
invalid_body | 400 | The request body does not match the schema. errors names each field. |
invalid_id | 400 | An id in the path is not a valid id. |
invalid_input | 400, 415 | Another input is not valid, for example an unreadable If-Match header or a body that is not JSON (415). |
invalid_query | 400 | The query parameters do not match the schema. |
listing_active | 409 | The listing is still published, so it cannot be deleted. |
listing_blocked | 409 | Athaus has blocked the listing. A key cannot lift that. |
listing_closed | 409 | The property is sold or let and does not go online again. |
listing_incomplete | 409 | The listing lacks details needed to publish it. errors names what is missing. |
listing_not_online | 409 | The listing is not running, so there is nothing to take offline. |
listing_not_unit | 409 | The listing is not a unit of a new-build project, so it has no unit status. Assign it to a project with POST /projects/\{externalProjectId\}/assign. |
listing_reserved | 409 | The property is reserved. Lift the reservation first, then publish. |
mailbox_not_connected | 409 | No mailbox is connected. A reply goes out only from the mailbox of the office. |
method_not_allowed | 405 | The path exists, but not for this method. The header Allow lists the methods that work. |
not_found | 404 | There is nothing under this id or address, or it belongs to another office. |
payload_too_large | 413 | The request body is larger than 512 KB, the file of POST /v1/medias is larger than 25 MB, the listing would hold more than 40 files or 500 MB, or 200 files already wait for a listing in the office. |
plan_required | 403 | The plan of the office does not include API access. |
precondition_failed | 412 | The condition in If-Match or If-None-Match does not hold. Read the resource again and retry with its new ETag. |
profile_unsupported | 400 | The request has a countrySpecific section for a country that has no profile yet. |
project_not_empty | 409 | The project still has units, so it cannot be deleted. Release them with POST /projects/\{externalProjectId\}/unassign first, or delete the listings. |
project_unit_limit_exceeded | 409 | A project holds at most 1000 units, and this call would take it past that. The answer says how many it holds and how many the call would add; nothing was changed. Create a second project, or release units with POST /projects/\{externalProjectId\}/unassign. |
proposal_already_decided | 409 | The proposal was already approved, rejected or has expired. |
rate_limited | 429 | Too many requests. Wait for Retry-After. |
reference_already_exists | 409 | This reference already belongs to something else in the office: offererMarketingKey to another listing, externalMediaId to a file that waits for a listing. |
test_office_busy | 409 | The test office is being built or reset. Try again in a few seconds. |
test_office_full | 403 | The test office is full. Delete some data or reset it. |
401 | The key is missing, invalid or revoked. | |
unit_already_exists | 409 | The project already has a unit with this number. errors names each affected unit by its position in the body; nothing was created. |
unit_status_invalid | 409 | This status does not fit the distribution type of the project: a rental project knows rented, a project for sale sold. |
upcoming_viewings_exist | 409 | The listing has upcoming viewings. Deleting it would cancel them. |
webhook_endpoint_limit_exceeded | 409 | The office has reached the maximum number of webhook endpoints. |
Keep reading
REST API: errors as problem details
Every error from /v1 is an RFC 9457 problem with a real HTTP status, a code to branch on and a request id for support.
REST API: limits and throttling
How many calls /v1 accepts per key and per office, which headers show the state and what to do on a 429.
Error codes of the app and the MCP servers: what each code means
Every code the app and the MCP servers return, with its meaning. Generated from the registry they are typed against.