---
title: "REST API Responses"
description: "REST API Responses"
keywords: "REST API Responses"
url: "https://www.myrapidi.com/wiki/rest_api_responses"
locale: "en"
published: "2017-08-02T11:56:54Z"
modified: "2023-04-03T08:20:35Z"
---

All response bodies are [JSON](http://en.wikipedia.org/wiki/JSON) or [JSON API](http://www.jsonapi.org "JSON API") encoded.

**JSON:**

A single resource is represented as a **JSON** object:

```
{
    "field1": "value",
    "field2": true,
    "field3": []
}
```

Below is a specific example of a single resource presented as a **JSON** object:

```
{
    "code": "CUST",
    "description": "Customer Transfers",
    "comments": []
  }
```

A collection of resources is represented as a **JSON** array of objects:

```
[
    {
      "field1": "value",
      "field2": true,
      "field3": []
    },
    {
      "field1": "another value",
      "field2": false,
      "field3": []
    }
]
```

Below a specific example of a collection of resources represented as a **JSON** array of objects:

```
[ 
  { 
    "code": "CUST01", 
    "description": "Customer Transfers", 
    "comments": [] 
  }, 
  { 
    "code": "CONTACT", 
    "description": "Contact Transfers", 
    "comments": 
      ["created_at": 2017-08-27T16:14:57Z", 
        "created_by": "xxname", 
        "comment": "updated transfer" }, 
        "created_at": 2017-08-28T15:19:34Z", 
        "created_by": "xxname", 
        "comment": "<p>adjusted</p> - ready to run"} 
      ] 
  }, 
    "code": "Invoice" ,
    "description": "Invoice Transfers", 
    "comments":[] 
  }, 
  ... 
]
```

**JSON API:**

A single resource is represented as a **JSON API** object:

```
{
  "data":{ 
    "id": "1", 
    type": "groups", 
    "attributes": 
      { "code": "codename", 
        "description": "description of group" 
      }, 
      relationships":{ 
        "comments": {} 
      } 
    } 
  } 
}
```

Below a specific example of a single resource **JSON API** object:

```
{ 
  "data": 
    [{ 
      "id": "8", 
      "type": "groups", 
      "attributes": { 
        "code": "CUST01", 
        "description": "Customer Transfers" 
      }, 
      "relationships": { 
        "comments": { 
          "data": [] 
        } 
      } 
    }] 
  } 
}
```

A collection of resources is represented as a **JSON API** array of objects:

```
{ 
"data": 
  [ 
    { 
      "id":"1", 
      "type":"groups", 
      "attributes":{ //...this groups'attributes 
        "code": "codename", 
        "description": "description of group" 
      }, 
      "relationships": 
        { //...this groups'relationships 
          "comments": { 
            "data": [ 
              { 
                "id":"5", 
                "type":"comments" 
              }, 
              { 
                "id":"6", 
                "type":"comments" 
              } 
            ] 
          } 
        } 
    } 
  ], 
"included":  
  [ 
    { 
    "type": "comments", 
    "id": "5", 
    "attributes": { 
      "created_at": "yyyy-mm-ddThh:mm:ssZ", 
      "created_by": "author-name", 
      "comment": "text for the comment"} 
    }, 
    { 
      "type": "comments", 
      "id": "5", 
      "attributes": { 
        "created_at": "yyyy-mm-ddThh:mm:ssZ", 
        "created_by": "author-name", 
        "comment": "text for the comment" 
      } 
    } 
  ] 
}
```

Below a specific example of a collection of resources represented as a **JSON API** array of objects:

```
{ 
  "data": [ 
    { 
      "id": "8", 
      "type": "groups", 
      "attributes": { 
        "code": "CUST01", 
        "description": "Customer Transfers" 
      }, 
      "relationships": { 
        "comments": { 
          "data": [ 
          ] 
        } 
      } 
    }, 
    { 
      "id": "2", 
      "type": "groups", 
      "attributes": { 
        "code": "CONTACT", 
        "description": "Contact Transfers" 
      }, 
      "relationships": { 
        "comments": { 
          "data": [ 
            { 
              "id": "10", 
              "type": "comments" 
            }, 
            { 
              "id": "12", 
              "type": "comments" 
            } 
          ] 
        } 
      } 
     }, 
     { 
      "id": "5", 
      "type": "groups", 
      "attributes": { 
        "code": "INVOICE", 
        "description": "Invoice Transfers" 
      }, 
      "relationships": { 
        "comments": { 
          "data": [ 
          ] 
        } 
       } 
     }, 
... 
], 
"included": [ 
  { 
    "id": "10", 
    "type": "comments", 
    "attributes": { 
      "created-at": "2017-08-27T16:14:57Z", 
      "created-by": "xxname", 
      "comment-text": "updated transfer" 
     } 
   }, 
   { 
    "id": "12", 
    "type": "comments", 
    "attributes": { 
      "created-at": "2017-08-28 15:19:34Z", 
      "created-by": "xxname", 
      "comment-text": "

adjusted

- ready to run" 
    } 
  } 
]
```

Timestamps are in [UTC](http://en.wikipedia.org/wiki/Coordinated_Universal_Time) and formatted as [ISO8601](http://en.wikipedia.org/wiki/ISO_8601).

Unset fields will be represented as a `null` instead of not being present. If the field is an array, it will be represented as an empty array - ie `[]`.

#### HTTP Status Codes

We use HTTP status codes to indicate the success or failure of a request.

Success codes:

- `200 OK` - Request succeeded. Response included
- `201 Created` - Resource created.
- `204 No Content` - Request succeeded, but no response body.

Error codes:

- `400 Bad Request` - Could not parse the request
- `401 Unauthorized` - No authentication credentials (token) provided or authentication failed
- `403 Forbidden` - The Authenticated API user does not have access
- `404 Not Found` - Resource not found
- `415 Unsupported Media Type` - POST/PUT/PATCH request occurred without a `application/json` content-type
- `422 Unprocessable Entry` - A request to modify or create a resource failed due to a [validation error](#validation-error)
- `429 Too Many Requests` - Request rejected due to [rate limiting](http://dev.enchant.com/api/v1#ratelimit) 
- `500, 501, 502, 503, etc` - An internal server error occurred

#### Errors

All 400 series errors (400, 401, 403, etc) will be returned with a **JSON** or **JSON API** object in the body and a `application/json` or `application/vnd.api+json` content-type respectively.

```
{ "message": "Not Found" }
```

500 series error codes (500, 501, 502, etc) do not return **JSON** or **JSON API** bodies.

#### Validation Errors

In case of validation errors on a POST/PUT/PATCH request, a `422 Unprocessable Entry` status code will be returned. The JSON response body will include an array of error messages.

```
{ 
  "message": "Validation Failed", 
  "errors": [ 
    { 
      "message": "Field is not valid" 
    }, 
    { 
      "message": "OtherField is already used" 
    } 
  ] 
}
```