Return values & Errors

When a value is returned or an error occurs, the API clients will receive the necessary information in the http response.

The result of your request can be examined via http response status which can have the following values:

200 Ok : your request was processed successfully;
201 Created : your request resulted in a new resource created;
204 No Content : request has been successfully processed and that the response is intentionally blank;
400 Bad Request : the entity you passed has missing or invalid field values (you can see the validation exception in the http response);
401 Unauthorized : you did not include your credentials or you are not allowed to views the requested resources;
403 Forbidden : that the server refuses to fulfill the request;
404 Not Found : either you forgot to indicate the version or you have entered an incorrect url;
409 Conflict : The request could not be completed due to a conflict with the current state of the resource;
417 Expectation Failed : The expectation given in an Expect request-header field could not be met by this server;
422 Unprocessable Entity : The entity contains incorrect values for require fields/foreign keys;
500 Internal server: while processing your request some unknown error occurred;

Return Values

Return values from API calls will differ based on the operation.

GET: For successfull GET operations, the response will return HTTP 200 along with the requested data

E.g. if a request was sent to retrieve a job_type with an id of "46eea426-9de9-4ec2-b901-38b43be2f7f0", the response will be as follows :

HTTP 200 OK 
{
    "@odata.context":"https://developers.odysseemobile.com/api/$metadata#JobType/$entity",
    "id":"46eea426-9de9-4ec2-b901-38b43be2f7f0",
    "name":"Repair",
    "sales_organization_id":"0ea11d61-4e52-4eee-a945-bd8c26b52b45",
    "description":"Main type for repair",
    "is_default":true,
    "modified_dateutc":"2015-05-28T11:26:22Z",
    "code":"5656565654"
}

POST: For successfull POST operations, the response will return HTTP 201 along with the new entity created. For optimalization purpose (or for some requirements), you can adapt the request and specify prefer: return=minimal. With this, the POST/Put will only return you the id created/updated.

No matter of the controller you will call, you will always have the property id.

E.g. if a request was sent to create a new job_type entity, the response would be as follows:
```
HTTP 201 Created 
{
    "@odata.context":"https://developers.odysseemobile.com/api/$metadata#JobType/$entity",
    "id":"0fb727d0-4659-4b68-8a1e-641f9e8465fc",
    "name":"New Repair Type",
    "sales_organization_id":"00000000-0000-0000-0000-000000000000",
    "description":"New type of job",
    "is_default":false,
    "modified_dateutc":"2015-05-28T11:56:222Z",
    "code":""
}
        
```
PUT : For successfull PUT operations, the response will return the the whole entity (with always a field id). Similarly to the POST, if only the id value is required in the response, the prefer header should be set as prefer: return=minimal in the request.

E.g. if a request was sent to update a job entity with prefer: return=minimal, the response would be as follows :
```
HTTP 200 OK 8859412e-f8fc-4502-8276-14ac9973ef4d 
```
DELETE: For successfull DELETE operations, the response will return HTTP 204

E.g. if a request was sent to delete a job entity, the response would be as follows :
```
HTTP 204 No Content 
```

Errors

Errors could occur due to various reasons and these are informed to the user in a meaningfull way.

Possible error responses:

Authentication errors: If the API call request is not authenticated

E.g. if a request is made to retrieve all companies without providing the Authorization header

HTTP Error 401 Unauthorized: [{"error_code":"401","entity":"Authorization","error_property":[],"error_message":"Authorization property is not set. For more info, go to the API HELP / Authentification"}]

E.g. if a request is made to retrieve all companies with an invalid Authorization header

HTTP Error 403 Forbidden : [{"error_code":"403","entity":"Authorization","error_property":[],"error_message":"Authentication failed for the user. For more info, go to the API HELP / Authentification"}]

E.g. if a request is made to retrieve all companies with unauthorized user credentials

HTTP Error 403 Forbidden : [{"error_code":"403","entity":"Authorization","error_property":[],"error_message":"Authentication failed for the user. For more info, go to the API HELP / Authentification"}]

E.g. if a request user credentials not flagged as 'Allow throught API'

HTTP Error 403 Forbidden : [{"error_code":"403","entity":"Authorization","error_property":[],"error_message":"Authentication failed for the user. For more info, go to the API HELP / Authentification"}]

Data retrieval errors: If the API call request contains parameters that are not accurate.

E.g. if a request is made to retrieve a company with an id of "7fc8d57e-ea3b-4ed6-951d-82270709b6e6"(not a correct company id),
```
HTTP Error 404 Not Found : [{"error_code":"","entity":"user_unavailability","error_property":[],"error_message":"Entity not found"}]
```
Mandatory field errors: If the API call request does not provide mandatory fields as specified in the Reference Documentation.

E.g. if the user_id field in the user_unavailability entity is not populated,
```
HTTP Error 400 Bad Request Entity : [{"error_code":"","entity":"user_unavailability","error_property":["user_id","user_code","user"],"error_message":"user_id, user_code or user must be provided"}]
```
Field length errors: If the API call request contains fields that exceed the limit specified in the Reference Documentation.

E.g. if the description field in the user_unavailability entity exceeds 255 characters,
```
HTTP Error 400 Bad Request Entity : [{"error_code":"","entity":"user_unavailability","error_property":["description"],"error_message":"description shouldn't exceed 255 length"}]
```

Embedded entity errors: If the API call request does not provide any of the required fields to handle embedded entities.

E.g. when the request does not include values for user_unavailability_type_id, user_unavailability_type_code or user_unavailability_type when creating a user_unavailability

HTTP Error 400 Bad Request Entity : [{"error_code":"","entity":"user_unavailability","error_property":["user_unavailability_type_id","user_unavailability_type_code","user_unavailability_type"],"error_message":"user_unavailability_type_id, user_unavailability_type_code or user_unavailability_type must be provided"}]

Not exists errors: If the API call request contains field data that cannot be linked with existing data.

E.g. when the request does not include values for user_unavailability_type_id, user_unavailability_type_code or user_unavailability_type when creating a user_unavailability
```
HTTP Error 400 Bad Request Entity : [{"error_code":"","entity":"user_unavailability","error_property":["user_unavailability_type_id","user_unavailability_type_code"],"error_message":"The userunavailabilitytype does not exist in the database."}]
```

Error return Type

Accept Type is application/json

E.g. when adding or updation existing company, provided name empty or not provided following error will be return.
```
[{"error_code":"","entity":"company","error_property":["name"],"error_message":"name required"}]
```

Accept Type is application/xml

E.g. when adding or updation existing company, provided name empty or not provided following error will be return.

<api_errors xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <api_error>
        <error_code />
        <entity>company</entity>
        <error_property>
            <string>name</string>
        </error_property>
        <error_message>name required</error_message>
    </api_error>
</api_errors>

Odyssee Mobile

API User Guide

Return values & Errors

Return Values

Errors

Possible error responses:

Error return Type