# API error codes: what each code means

Adresse: https://docs.athaus.ai/en/api/errors

> Every code the REST API returns in the member code of a problem, with its HTTP status and meaning. Generated from the contract.

Type: Reference
Last updated: 2026-11-16

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](/en/api/v1/fehler). 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](/en/api/fehlercodes).

| 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.                                                                                                                                                                           |
| `billing_unavailable`                         | `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.                                                                                                                                                                                                             |
| `unauthorized`                                       | `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.                                                                                                                                                                                                    |
