API Responses

When an API finishes processing a request, it’ll return a response to indicate the outcome of the operation and provide the data to your app. Your app must know how to process that response, so that it can proceed accordingly. In this post, we’ll learn about the structure and content of an API response.

Response structure

An API response consists of the following parts:

• HTTP status code is a 3-digit value that indicates the outcome of the operation.

• HTTP headers provide additional information about the response.

• Body describes or contains the result of the requested action.

The following image shows an error response that the Smartsheet API returns when a GET User request specifies an invalid user ID.

HTTP status code

The HTTP status code is a 3-digit value that indicates the outcome of the requested operation. Whenever your app receives an API response, it should evaluate the HTTP status code and proceed accordingly.

There are five categories of HTTP status codes, identifiable by numeric range.

Category	Numeric range	Description
Informational	100-199	1xx codes indicate some type of acknowledgement. You’ll rarely see HTTP status codes in the 1xx range.
Successful	200-299	2xx codes indicate success.
Redirects	300-399	3xx codes indicate some type of redirection. You’ll rarely see HTTP status codes in the 3xx range.
Client errors	400-499	4xx codes indicate an error due to a problem with the request.
Server errors	500-599	5xx codes indicate an error due to a problem with the server.

Common HTTP status codes

There are many HTTP status codes, but some are more commonly seen than others. The documentation for the API you’re using should specify the codes that each operation may return. The most commonly used codes are in the 2xx, 4xx, and the 5xx range.

2xx status codes

Status codes in the 2xx range indicate success. The most common status code in the 2xx range is 200. If things are working well, you should receive this status code often.

• 200 OK. The request was successfully processed.

4xx status codes

Status codes in the 4xx range indicate a problem with the request. When your app receives a 4xx status code, it should evaluate the error details and attempt to fix the problem before retrying the request. Common 4xx status codes include:

• 400 Bad Request. The request contains invalid content or is not formatted correctly.
• 401 Unauthorized. The authorization credentials that the request specifies are missing or invalid.
• 403 Forbidden. The authorization credentials that the request specifies don’t correspond to an account that has the rights to perform the requested action.
• 404 Not Found. The resource or object that the request is attempting to access does not exist.
• 429 Too many requests. The user identified by the authorization credentials in the request has sent too many requests in a period of time.

5xx status codes

Status codes in the 5xx range indicate a problem with the server. You shouldn’t see them very often, but should still make sure your app can handle them appropriately. Common 5xx status codes include:

• 500 Internal Server Error. Indicates an unexpected condition on the server.
• 503 Service Unavailable. Indicates that the server is unavailable (e.g., due to excessive load or maintenance downtime).

HTTP headers

HTTP headers provide additional information that the client may use to process an API response. Each HTTP header is composed of a property name and a value (i.e., a name/value pair). An API response always includes HTTP headers and they may be used to specify things like:

• The type of content specified in the response body (Content-Type header).
• The size of the response body (Content-Length header).
• Other data about response.

Note: The documentation for the API you’re using should specify which response headers you should examine when processing a response. In the interest of brevity, examples in this post show only the Content-Type header.

Body

The contents of an API response body will depend on the type of operation that was requested and the outcome of that operation. Documentation for the API you’re using will describe the response body that’s returned for each operation, but many APIs implement the following behavior:

Request	Contents of response body
Successful POST	Data that describes or contains the result of the action.
Successful GET	Data that was requested.
Successful PUT	Data that describes or contains the result of the action.
Successful DELETE	Data that describes the result of the action or describes the deleted entity.
Error (any type of request)	Data that specifies details about the error. Typically contains information like a system-specific error code and message.

The body of an API response is typically specified in a format called JSON. At this point, don’t worry about trying to understand the JSON that’s shown in the examples below — we’ll cover that topic in the next post.

Example responses

Now that we’re familiar with the parts of an API response, let’s look at some examples.

Note: These are just examples. Response content will vary from API to API, and even from operation to operation within an API. Consult documentation for the API you’re using for details about its API responses.

Success responses (examples)

The following examples show some success responses from the Smartsheet API.

200 OK: data successfully created

The following response is returned by the Smartsheet API when a Create Folder (POST) request is successfully processed.

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "id": 1486948649985924,
    "name": "New folder"
  }
}

In this response:

• The HTTP status code 200 indicates that the request was successfully processed.
• The Content-Type header specifies that the body is formatted as JSON with character encoding UTF-8.
• Data within the body specifies the result of the operation and properties of the folder that’s been created.

200 OK: data successfully retrieved

The following response is returned by the Smartsheet API when a Get Folder (GET) request is successfully processed.

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

{
  "id": 7116448184199044,
  "name": "Projects",
  "permalink": "https://app.smartsheet.com/b/home?lx=B0_lvAtnWyge4Rfoa"
}

In this response:

• The HTTP status code 200 indicates that the request was successfully processed.
• The Content-Type header specifies that the body is formatted as JSON with character encoding UTF-8.
• Data within the body specifies properties of the folder that was requested.

200 OK: data successfully updated

The following response is returned by the Smartsheet API when an Update Folder (PUT) request is successfully processed.

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

{
  "message": "SUCCESS",
  "resultCode": 0,
  "result": {
    "id": 7960873114331012,
    "name": "New name for folder"
  }
}

In this response:

• The HTTP status code 200 indicates that the request was successfully processed.
• The Content-Type header specifies that the body is formatted as JSON with character encoding UTF-8.
• Data within the body specifies the result of the operation and properties of the updated folder.

200 OK: data successfully deleted

The following response is returned by the Smartsheet API when a Delete Folder (DELETE) request is successfully processed.

HTTP/1.1 200 OK

Content-Type: application/json;charset=UTF-8

{
  "message": "SUCCESS",    
  "resultCode": 0
}

In this response:

• The HTTP status code 200 indicates that the request was successfully processed.
• The Content-Type header specifies that the body is formatted as JSON with character encoding UTF-8.
• Data within the body specifies the result of the operation. Although this example doesn’t do so, some APIs will also specify properties of the deleted item in the body of a DELETE response.

Error responses (examples)

The following examples show some different types of error responses from the Smartsheet API.

400 Bad Request

The following error response is returned by the Smartsheet API when a request specifies an invalid property name.

HTTP/1.1 400 Bad Request

Content-Type: application/json;charset=UTF-8

{
    "errorCode": 1008,
    "message": "Unable to parse request. The following error occurred: Unknown attribute \"siblng\" found at  line 3, column 41",
    "refId": "bb6vnwyra6w3"
}

In this response:

• The HTTP status code 400 indicates that the request failed because it contained invalid content or was not formatted correctly.
• The Content-Type header specifies that the body is formatted as JSON with character encoding UTF-8.
• Data within the body specifies system-specific details about the error.

403 Forbidden

The following error response is returned by the Smartsheet API when a request specifies an invalid token value in the Authorization HTTP header.

HTTP/1.1 403 Forbidden

Content-Type: application/json;charset=UTF-8

{
    "errorCode": 1004,
    "message": "You are not authorized to perform this action.",
    "refId": "gzujvnbanuyd"
}

In this response:

• The HTTP status code 403 indicates that the request failed because the authorization credentials that the request specified don’t correspond to an account that has the rights to perform the requested action.
• The Content-Type header specifies that the body is formatted as JSON with character encoding UTF-8.
• Data within the body specifies system-specific details about the error.

404 Not Found

The following error response is returned by the Smartsheet API when a request specifies an invalid ID for the user that it’s requesting.

HTTP/1.1 404 Not Found

Content-Type: application/json;charset=UTF-8

{
    "errorCode": 1020,
    "message": "User not found.",
    "refId": "ookmfyguq538"
}

In this response:

• The HTTP status code 404 indicates that the request failed because the object that the request attempted to access does not exist.
• The Content-Type header specifies that the body is formatted as JSON with character encoding UTF-8.
• Data within the body specifies system-specific details about the error.

503 Service Unavailable

The following error response is returned by the Smartsheet API when the Smartsheet service is offline for maintenance.

HTTP/1.1 503 Service Unavailable

Content-Type: application/json;charset=UTF-8

{
    "errorCode": 4001,
    "message": "Smartsheet.com is currently offline for system maintenance. Please check back again shortly.",
    "refId": "ookmfyguq538"
}

In this response:

• The HTTP status code 503 indicates that the request failed because the service is unavailable.
• The Content-Type header specifies that the body is formatted as JSON with character encoding UTF-8.
• Data within the body specifies system-specific details about the error.

So there you have it…

…everything you need to know about the fundamentals of API Responses! Next, we’ll take a closer look at JSON — the data format that’s used in API requests and responses. But first — a quick knowledge check: