HTTP Response Codes and Errors

Purpose: Describes the HTTP responses that your application can receive from UCS.

Introduction

The Universal Contact Server returns HTTP status codes and messages for every operation, in the requested format. Status codes match standard HTTP codes, but messages can differ and provide additional details included in the header of the response.

Important

Additional result and error codes may be returned due to external web servers and layers involved in your operations.

Read Log Lines

Log lines are compliant with the following syntax:

 14:33:39.485[1] Trc[2] 29998 [let-3851106] 2010-04-02[3]    14:33:39[3]    127.0.0.1[4]    
 8080[5]    GET[6]    /cv/server/status[7]    -    200[8]    -    0    2[9]    
 http://localhost:8080[10]    Apache-HttpClient/4.0-beta2 (java 1.5)[11]    -

• [1] = timestamp
• [2] = loglevel
• [3] = date and time when the request was received
• [4] = ip address
• [5] = server port
• [6] = http method
• [7] = requested url
• [8] = http response code
• [9] = execution time in ms
• [10] = called host/port
• [11] = user agent making the call

Successful Result

A successful response to a request is marked by HTTP Status Code 200 (OK). In that case, your application may get additional information in the header and the body of the response. Refer to the Response section of your operation's page to get the detailed list of returned information. Questions about the returned content can be submitted as comments in this wiki. The following table lists the standard HTTP codes used by Context Services for a successful response.

Successful results

Code	Title	Description
200	OK	Success!
201	Created	The request has been fulfilled and resulted in a new resource being created.
204	No Content	The operation was successful and returned with no content.

Errors

For responses with HTTP status code 4xx or 5xx, the response body contains an application-specific description of the error instead of a representation of the requested resource. Context Services errors consist of an application-specific error code and description, and are formatted in JSON as follows:

error = {
 "http_method" : "POST",
"title" : "bad parameter",
"description" : "bad parameter 'server mode' reason : server mode has not a correct value 'something'",
"code" : 4020,
"uri" : "http://localhost:8080/server/mode"
}

The following table lists the specific errors that operations can encounter. This list is not restrictive; additional error codes could be returned due to external web servers and layers involved:

Errors

Code	Title	Description
303	See Other	General error which can occur if your application refers to a URI which moved, due to API changes.
400	Bad Request	General error which can be one of the following reasons: Missing required parameter. Parameter value of unexpected type. Invalid object syntax if you used JavaScript objects in your operation's input. Missing required attribute if you used JavaScript objects in your operation's input.
401	Not Authorized	Credentials are missing or incorrect, or the given user is not allowed to execute a given service (such as an administrative service method that changes the profile schema).
403 Not available for now.	Forbidden	The operation is forbidden and the reason is specified in the error message. This error is returned in the following cases: Attempt to query customer profile or service information when the server is in Maintenance Mode. Attempt to alter the schema while the server is in Production Mode. Attempt to add customer profiles prior to the definition of a profile schema. Attempt to change the server mode times out, due to maintenance operations or schema modifications to complete.
404	Not Found	The specified URI is invalid, or the requested resource (such as a customer, service, state, task, extension, or identification key) does not exist.
405	Method Not Allowed	Returned when an unsupported operation is requested. For instance, if a resource supports only PUT and GET operations, a POST request on this resource returns this error.
415	Unsupported Media Type	In the header of your request, Content-Type is not set to a valid value. Most operations of Context Services support only "application/json". Check the operation description in the API.
500	Internal Server Error	An unexpected error occurred in UCS (for instance, a runtime exception). The error message suggests to forward logs to Genesys Customer Support.
502	Bad Gateway	Returned when one or more of the backend systems required to fulfill the response (the CV database or UCS, for example) are either unavailable or returned an error. Context Services is not responsible for this message. This error may occur due to external proxies or cache involved in your operation.
503	Service Unavailable	UCS is unable to process the given request. Example situations include: Requests on a whole, or for a specific client/tenant/role, are being throttled. The server is switching from production to maintenance mode, or vice versa, and does not accept requests for the moment.