Skip to content

Responses

Each request to the IS24 Rest API will result in a response. A response contains an HTTP status code, a response header and a response body. While GET requests often return the requested resource in the specified media type (representation) as body content, other requests might answer with a result message in the body (see below for the XML structure of messages within the body).

Note that:

  • While some error responses - for technical reasons - only include a plain text error message in the body, beside the status code, other errors yield in a response with a message in the requested media type in the body. A so called message response contains at least one message which includes a message code and a meaningful description.

The following page shows the possible HTTP status codes used within the RESTful webservice with a short description what that code means and for each status code the possible well formated messages.

Every possible message code is also listed in a XSD schema: here

HTTP status codes, message codes and messages

200 OK

description

The requested operation was successful (e. g. GET, PUT, DELETE).

header

Nothing special

body

messageCode message
MESSAGE_RESOURCE_UPDATED Resource [NAME] with id [ID] has been updated
MESSAGE_RESOURCE_DELETED Resource [NAME] with id [ID] has been deleted
MESSAGE_OPERATION_SUCCESSFUL Operation successful executed

201 Created

description

This status code is returned after a new entity of a resource was successfully created. Additionally you can find a link to the new created resource using the returned HTTP Location header.

header

Nothing special

body

messageCode message
MESSAGE_RESOURCE_CREATED Resource [NAME] with id [ID] has been created

401 Authentication Required

description

If you want to access a protected resource, an authentication (user and/or system authentication) is required. It is important to know, that some resources are restricted to specific users or systems. Also all errors while executing authentication will be handled as 401.

header

WWW-Authenticate = Challenge and realm (OAauth realm="IS24 API")

body

messageCode message comment
ERROR_COMMON_AUTHENTICATION_REQUIRED Authentication is required for this operation The requested resource requires authentication (indeed all ImmoScout24 resources require at least system authentication, known as 2-legged) - consult the documentation of the specific resource which authentication objects are needed for that resource.
ERROR_COMMON_AUTHENTICATION_OAUTH_NONCE_EXPIRED Authentication is required for this operation This is a more specialized message code if the API nonce is expired. If the user has a wrong time setting his client will send a corrupt timestamp. With this message code you can give feedback to the user to change his time setting

403 Access Denied

description

If you want to access a protected resource, an authentication (user and/or system authentication) is required. It is important to know, that some resources are restricted to specific users or systems. This means the authentication was successful but the authenticated system/user does not have the permission to access the protected resource.

header

Nothing special

body

messageCode message
ERROR_COMMON_ACCESS_DENIED No authorization for this operation

404 Not found

description

A requested entity of a specific resource does not exist (e. g. wrong id). Remove the id from the URI and try to get a list of available entities of the specific resource.

Note: It is possible that an entity of a subresource exists, but prior id's in the URI are wrong (e.g. an entity of a parent resource is missing, the id is misspelled). Normally, if a path segment or resource does not exists, the server returns 404. If a method is not applicable to a resource or subresource, the server returns 405 Method not allowed instead.

header

Nothing special

body

messageCode message
ERROR_RESOURCE_NOT_FOUND Resource [NAME] with id [ID] not found
ERROR_COMMON_RESOURCE_NOT_FOUND Resource was not found

405 Method not allowed

description

This status is returned if you try to apply an operation to an existing existing resource that is not supported; e. g. you add an id to a resource URL for a POST operation, while no id is allowed or you have a read-only resource. If the resource, a parent resource or an entity of a resource does not exist, the server always returns 404.

header

Nothing special

body

messageCode message
ERROR_COMMON_METHOD_NOT_ALLOWED Method not allowed for this resource

406 Not acceptable

description

The resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request. See Representations for further information.

header

Nothing special

body

messageCode message
ERROR_COMMON_ACCEPT_TYPE_NOT_APPLICABLE Accept type not applicable

409 Conflict

description

Occurs if a resource is accessed concurrently (in a transactional scope) or if you try to create a new entity of a resource (using POST) using an id that already exists (unique constraint violation).

header

Nothing special

body

messageCode message
ERROR_COMMON_REQUEST_CONFLICT A conflict occured during execution of an operation (e.g. on a resource)

412 Precondition

description

Validation exception (e. g. missing or wrong data). Verify the body for syntactical errors (e. g. a malformed XML structure, missing required elements or attributes, wrong or missing namespaces) and parameters for correct data types and/ or ranges. If you provide wrong data (e. g. a wrong or misspelled id) which is used to identify an entity of a resource, a 404 should be thrown.

header

Nothing special

body

messageCode message
ERROR_COMMON_RESOURCE_REQUIRED The requested resource requires the resource [NAME] as precondition
ERROR_COMMON_SCHEMA_VALIDATION_FAILED The request is not schema valid. [REASON: ERROR_DESCRIPTION]
ERROR_COMMON_URL_PARAMETER_REQUIRED The parameter [NAME] is missing in the request URL
ERROR_COMMON_URL_PARAMETER_VALIDATION_FAILED The parameter [NAME] has an invalid value [VALUE]
ERROR_COMMON_URL_PARAMETER_NOT_SUPPORTED The parameter [NAME] is not supported
ERROR_COMMON_HEADER_PARAMETER_VALIDATION_FAILED The parameter [NAME] has an invalid value [VALUE]
ERROR_COMMON_URL_MULTIPLE_PARAMETERS_NOT_ALLOWED Only one of the parameters [NAME, NAME, ...] can be set
ERROR_RESOURCE_NOT_SUPPORTED The requested resource [NAME] is not supported by the specific resource [NAME] (e.g. savedsearch is only available for searchers)
ERROR_RESOURCE_VALIDATION Error while validating input for the resource. [REASON: ERROR_DESCRIPTION]
ERROR_CONTACT_DETAILS_MISSING There are some contact details missing
ERROR_INVALID_COORDINATES The given coordinates are invalid, e.g. 90/90
ERROR_GEOCODING_FAILED The geocoding was not successful, e.g. an address was given which does not exist
INTERNATIONAL_ADDRESS_NOT_ALLOWED For this kind of realEstateType an international address is not allowed. Check if your request body contains appartmentBuy, houseBuy, livingBuySite or tradeSite

415 Unsupported Media Type

description

If you want to transmit data using POST or PUT you must set a HTTP Content-Type header with a supported media type (representation). If you want to retrieve information you must the a HTTP Accept header with a supported media type (representation). Note: For technical reasons sometimes the server will return a status code of 404 instead of 406 or 415, if you provide a not supported mime type as Accept header. See Representations for further information.

header

Nothing special

body

messageCode message
ERROR_COMMON_MEDIA_TYPE_UNSUPPORTED Media type is not supported

500 Internal server error

description

An unexpected or fatal error has occurred. This should never happen. Please contact the API support and supply detailed information / preconditions / error id.

header

Nothing special

body

messageCode message
ERROR_COMMON_INTERNAL_SERVER_ERROR Internal Server Error.[ERROR ID:[ID] MESSAGE: [DESCRIPTION]]

501 Not Implemented

description

The server does not support the functionality required to fulfill the request. This is the appropriate response when the server does not recognize the request method and is not capable of supporting it for any resource.

header

Nothing special

body

messageCode message
ERROR_COMMON_NOT_IMPLEMENTED The method is not yet implemented

502 Bad gateway

description

The server, while acting as a gateway or proxy, received an invalid response from the upstream server it accessed in attempting to fulfill the request.

503 Temporarily Not Available

description

An unexpected or fatal error has occurred (server / database etc. not available). This should never happen. Please contact the API support and supply detailed information / preconditions / error id.

header

Nothing special

body

messageCode message
ERROR_COMMON_SERVICE_UNAVAILABLE The service is temporally not available.[ERROR ID:[ID] MESSAGE: [DESCRIPTION]]

XML schema of the responses

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<xs:element name="messages">
    <xs:complexType>
        <xs:sequence>
            <xs:element maxOccurs="unbounded" name="message" type="Message"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>  

<xs:complexType name="Message">
    <xs:all>
        <xs:element name="messageCode" type="MessageCode"/>
        <xs:element name="message" type="xs:string"/>
    </xs:all>
</xs:complexType>

Example responses in XML and JSON

XML

1
2
3
4
5
6
<common:messages xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0">
    <message>
        <messageCode>ERROR_RESOURCE_NOT_FOUND</messageCode>
        <message>Resource [searcher] with id [test@test.de] not found.</message>
    </message>
</common:messages>

JSON

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "common.messages": [
    {
      "message": {
        "messageCode": "ERROR_RESOURCE_NOT_FOUND",
        "message": "Resource [searcher] with id [test@test.de] not found."
      }
    }
  ]
}

Additional field "id" for POST and DELETE requests

XML

1
2
3
4
5
6
7
<common:messages xmlns:common="http://rest.immobilienscout24.de/schema/common/1.0">
    <message>
        <messageCode>MESSAGE_RESOURCE_CREATED</messageCode>
        <message>Resource [RESOURCE] with id [ID] has been created.</message>
        <id>ID</id>
    </message>
</common:messages>

JSON

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "common.messages": [
    {
      "message": {
        "messageCode": "MESSAGE_RESOURCE_CREATED",
        "message": "Resource [RESOURCE] with id [ID] has been created.",
        "id": ID
      }
    }
  ]
}