> For the complete documentation index, see [llms.txt](https://developers.talentlyft.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.talentlyft.com/responses.md).

# Responses

The API returns HTTP responses on each request to indicate the success or otherwise of API requests. The codes listed below are often used, and the API may use others.

## Response codes

Successful API responses will have a 2xx HTTP status code.

| Success code | Description                                                                               |
| ------------ | ----------------------------------------------------------------------------------------- |
| 200          | Ok - The request has succeeded.                                                           |
| 201          | Created - The request has succeeded and a new resource has been created as a result of it |
| 204          | No Content - There is no content to send for this request, but the headers may be useful  |

Note that 4xx and 5xx responses may be returned for any request and clients should cater for them.

| Error code | Description                                                                                                                                      |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| 400        | Bad Request - Your request included invalid JSON                                                                                                 |
| 401        | Unauthorized - You have not been authenticated                                                                                                   |
| 403        | Forbidden - You have been authenticated, but you don't have a permission for the requested resource                                              |
| 404        | Not Found - The resource you requested could not be found                                                                                        |
| 409        | Conflict                                                                                                                                         |
| 422        | Unprocessable Entity - used for validation errors                                                                                                |
| 429        | Too many requests                                                                                                                                |
| 500        | Server errors - something went wrong with TalentLyft's servers.                                                                                  |
| 502        | Server errors - something went wrong with TalentLyft's servers.                                                                                  |
| 503        | These responses are most likely momentary operational errors (e.g. temporary unavailability), and, as a result, requests should be retried once. |
| 504        | These responses are most likely momentary operational errors (e.g. temporary unavailability), and, as a result, requests should be retried once. |

## Validation

Methods that take input will validate all parameters. Any parameter that fails validation will trigger an error response with status HTTP 422. The response body will be a JSON object that includes a message as well as a list of fields that failed validation.

```javascript
{
  "Message": "Validation Failed",
  "Errors": [
    {
      "Message": "This is a model-wide error"
    },
    {
      "Field": "Url",
      "Message": "'Url' should not be empty."
    }
  ]
}
```

Pagination

Some list resources in the API are paginated by default to allow clients to traverse data over multiple requests. Their responses may contain a `Pages`object that contains pagination links a client can use to traverse the data without having to construct a query. The [link relations](https://www.iana.org/assignments/link-relations/link-relations.xhtml) for the`Pages`field are as follows

| Parameter | Description                                                                                                    |
| --------- | -------------------------------------------------------------------------------------------------------------- |
| Next      | A link to the next page of results. A response that does not contain link does not have further data to fetch. |
| Prev      | A link to the previous page of results.                                                                        |
| First     | A link to the first page of results.                                                                           |
| Last      | A link to the last page of results.                                                                            |

## Pagination 

Pagination page out of bounds: return 200 status code - with empty array as data. In addition, you should provide hyperlinks to point clients to "correct" pages, for example the first page or the last "valid" page.

```javascript
{
  "Pages": {
    "First": "href": "http://example.org/api/user",
    "Prev": "href": "http://example.org/api/user?page=2",
    "Next": "href": "http://example.org/api/user?page=4",
    "Last": "href": "http://example.org/api/user?page=133"
  },
  "PerPage": 50,
  "Page": 1,
  "Count": 100,
  "Results": [
    {
      "Param1": "test1",
      "Param2": "test2",
    },
    {
      "Param1": "test1",
      "Param2": "test2",
    }
  ]
}
```