Error

View as Markdown

Error

Error describes why a request failed. The SDK does not throw when the API rejects a request or the network fails. It passes an Error to the callback instead. Use this class to

  • read the error message to log or show
  • read the Contentstack error code or the HTTP status to choose a response in your app
  • read the field-level details that the API returns for some errors

Every request callback in the SDK receives an Error argument, for example onCompletion(ResponseType responseType, Error error) on the callback of an entry fetch. On success error is null. On failure it holds an Error and the result is empty.

getErrorCode

getErrorCode returns the code that identifies why the request failed.

Returns: int. The Contentstack error code, or the HTTP status when the API sent none.

Validation

  • There is no client-side validation. getErrorCode reads a stored value and does not throw.

Behavior

  • When the API answers with an error response that carries an error_code, getErrorCode returns that Contentstack error code. Look the code up in the Content Delivery API Errors list.
  • When the response carries no error_code, getErrorCode returns the HTTP status, the same value as getStatusCode.
  • getErrorCode returns 0 when no response arrives, for example on a timeout or with no connection.
  • getErrorCode returns 408 when the SDK detects no network connection and does not send the request.
  • On a Taxonomy error, getErrorCode returns the error_code of the response, or 0 when the response has none.

Example

Basic usage: react to the error code of a failed fetch

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
    entry.fetch(new EntryResultCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, Error error) {
            if (error == null) {
                Log.d("Contentstack", entry.getTitle());
            } else if (error.getErrorCode() == 0) {
                // No response arrived, for example a timeout
                Log.e("Contentstack", "Network failure: " + error.getErrorMessage());
            } else {
                // The API rejected the request
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getErrorMessage

getErrorMessage returns the message that describes why the request failed.

Returns: String. The error message of the failed request.

Validation

  • There is no client-side validation. getErrorMessage reads a stored value and does not throw.

Behavior

  • When the API answers with an error response, the message is the error_message value of the response body.
  • When the response has no error_message, or an empty one, the SDK uses its own default message.
  • When no response arrives, for example on a timeout, the message comes from the network exception. When the exception has no message, the SDK uses its default message.
  • When the SDK creates the error itself, the message describes that case, for example a missing network connection or an entry missing from the cache.
  • Read the message for logs. Base decisions in your code on getErrorCode or getStatusCode, because the SDK can reword its own messages in any release.

Example

Basic usage: log the message of a failed fetch

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
    entry.fetch(new EntryResultCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, Error error) {
            if (error == null) {
                Log.d("Contentstack", entry.getTitle());
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getErrors

getErrors returns the details that the API sends for each field or value that failed, with field names as keys.

Returns: HashMap. The field-level error details, or null when the response has none.

Validation

  • There is no client-side validation. getErrors reads a stored value and does not throw.

Behavior

  • The declared return type is HashMap<String, Object>.
  • When the error response carries an errors object, the map holds one entry per key of that object. Each value is the value from the response as the SDK's JSON parser reads it, for example a JSONArray of messages.
  • When the errors value of the response is not an object, the map holds one key, errors, with that value.
  • getErrors returns null when the error response has no errors key. Check for null before you read the map.
  • When no response arrives, for example on a timeout or with no connection, the map holds one key, errors, whose value names the network exception.
  • On a Taxonomy error, and on most errors that the SDK creates itself, the map is empty.

Example

Basic usage: log the field-level details of a failed fetch

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

import java.util.HashMap;
import java.util.Map;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
    entry.fetch(new EntryResultCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, Error error) {
            if (error == null) {
                Log.d("Contentstack", entry.getTitle());
                return;
            }
            // The API rejected the request or the network failed
            Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                    + error.getErrorCode() + " " + error.getErrorMessage());
            HashMap<String, Object> details = error.getErrors();
            if (details != null) {
                for (Map.Entry<String, Object> detail : details.entrySet()) {
                    Log.e("Contentstack", detail.getKey() + ": " + detail.getValue());
                }
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}

getStatusCode

getStatusCode returns the HTTP status code of the error response, for example 422.

Returns: int. The HTTP status code of the failed request.

Validation

  • There is no client-side validation. getStatusCode reads a stored value and does not throw.

Behavior

  • When the API answers with an error response and a JSON body, getStatusCode returns the HTTP status of that response.
  • getStatusCode returns 0 in the cases below, where the SDK has no HTTP status to report:
    • No response arrives, for example on a timeout or with no connection.
    • The error response body is not JSON, for example an HTML page from a proxy.
    • The SDK creates the error itself without a request, for example when it detects no network connection.
    • The request comes from Taxonomy, whose errors carry only a message and an error code.
  • Use getErrorCode for the Contentstack error code, which tells two errors with the same HTTP status apart.

Example

Basic usage: handle a server error from a failed fetch

import android.util.Log;

import com.contentstack.sdk.Config;
import com.contentstack.sdk.Contentstack;
import com.contentstack.sdk.Entry;
import com.contentstack.sdk.EntryResultCallBack;
import com.contentstack.sdk.Error;
import com.contentstack.sdk.ResponseType;
import com.contentstack.sdk.Stack;

try {
    Config config = new Config();
    config.setHost("cdn.contentstack.io"); // your region's host, see Config setHost
    Stack stack = Contentstack.stack(context, "<API_KEY>", "<DELIVERY_TOKEN>", "<ENVIRONMENT>", config);
    Entry entry = stack.contentType("<CONTENT_TYPE_UID>").entry("<ENTRY_UID>");
    entry.fetch(new EntryResultCallBack() {
        @Override
        public void onCompletion(ResponseType responseType, Error error) {
            if (error == null) {
                Log.d("Contentstack", entry.getTitle());
            } else if (error.getStatusCode() >= 500) {
                // The server failed. The SDK does not retry, so try again later.
                Log.e("Contentstack", "Server error: " + error.getErrorMessage());
            } else {
                // The API rejected the request or the network failed
                Log.e("Contentstack", "Request failed: " + error.getStatusCode() + " "
                        + error.getErrorCode() + " " + error.getErrorMessage());
            }
        }
    });
} catch (Exception e) {
    // Contentstack.stack throws when a credential is null
    Log.e("Contentstack", "Setup failed: " + e.getMessage());
}