Responses

Each request to the IS24 Rest API will result in a response. A response contains a 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).

  • 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:
    http://rest.immobilienscout24.de/restapi/api/offer/v1.0/?_wadl&_schema&_file=classpath:/de/is24/common/webservice/xml/includes/messages-1.0.xsd

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

Description of the problem as plain text or the following message responses.

messageCode message comment
ERROR_COMMON_AUTHENTICATION_REQUIRED Authentication is required for this operation.  

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

Description of the problem as plain text or the following message responses.

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

Description of the problem as plain text or the following message responses.

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

Description of the problem as plain text or the following message responses.

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

Description of the problem as plain text or the following message responses.

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

Description of the problem as plain text.

messageCode

ERROR_COMMON_REQUEST_CONFLICT

message

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

Description of the problem as plain text or the following message responses.

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

Description of the problem as plain text or the following message responses.

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

Description of the problem as plain text or the following message responses.

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

Description of the problem as plain text or the following message responses.

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.

header

tbd

body

tbd

messageCode, message (tbd)

 

 

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 Description of the problem as plain text or the following message responses.

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

XML schema of the responses

<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

<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

{
  "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

<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

{
  "common.messages": [
    {
      "message": {
        "messageCode": "MESSAGE_RESOURCE_CREATED",
        "message": "Resource [RESOURCE] with id [ID] has been created.",
        "id": ID
      }
    }
  ]
}