How to catch and handle REST error responses

All Telligent Evolution platform REST API responses contain special Errors, Warnings, and Info collections of messages. In many cases these can contain information useful for telling us why our request failed or letting us know additional information that we may find useful. The Info collection can contain a message that an item was successfully deleted when we send a request to delete something. The Warnings collection can contain additional information that is important but was not severe enough to stop the current operation, like if a user is updated but for some reason their password could not be updated or if a blog post is created but it is identified as spam.

If any errors occur, either in input validation of the request itself or during the course of the intended operation, that do not allow the operation to be completed properly the response returned will contain those errors in the Errors collection and the response will have a response code of 500. When making requests with WebClient or HttpWebRequest any response codes of 500 will trigger a WebException and if not handled properly you may never see the underlying errors that were returned by the Telligent Evolution REST API.

Below is a code sample that you may find useful for handling REST error responses. This code sample is calling the SHOW Users endpoint with a username that does not belong to any existing user. The site cannot find a user with that username and will return an error message indicating so.

var webClient = new WebClient();

var key = String.Format("{0}:{1}", _apikey, _username);
var keyBase64 = Convert.ToBase64String(Encoding.UTF8.GetBytes(key));

webClient.Headers.Add("Rest-User-Token", keyBase64);

string response = string.Empty;
try
{
    response = webClient.DownloadString(_url + "/api.ashx/v2/users/alexc.xml");
}
catch(WebException ex)
{
    // an error has occured, let's figure out what
    // REST returns:
    // 404 -- If the *endpoint* cannot be found
    // 403 -- If the credentials are invalid
    // 500 -- Any errors are in the errors collection (as in this case)
    // 200 -- The request is processed successfully without errors

    var responseCode = ((HttpWebResponse) ex.Response).StatusCode;

    // if it is a 404 we know the endpoint URL is wrong
    if (responseCode == HttpStatusCode.NotFound)
    {
        // log it
    }
    // if it is a 403 then know something is wrong with our authentication / credentials
    else if (responseCode == HttpStatusCode.Forbidden) 
    {
        // log / handle it
    }
    // if it is a 500 then we should go ahead and get the response body and examine it 
    // to determine what the issue is
    else if (responseCode == HttpStatusCode.InternalServerError)
    {
        using (var reader = new StreamReader(ex.Response.GetResponseStream()))
        {
            response = reader.ReadToEnd();                       
        }
     }
     else {
         // otherwise log/handle the error
     }
}
catch(Exception)
{
    // log or otherwise handle error
}

// add code here to check to see if there are any messages in the 
// Errors collection, handle/log if so. Otherwise we should be good
    
     
//in this case our response is:
//<?xml version="1.0" encoding="utf-8"?>
//<Response>
//  <Info />
//  <Warnings />
//  <Errors>
//      <Message>Unable to retrieve user</Message>
//  </Errors>
//</Response>