> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beem.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# API responses

> HTTP status codes and API response codes returned by the Contacts API.

This section describes HTTP status codes and corresponding API response codes returned by the Contacts API.

***

## Success responses

| Code  | Description                                                   |
| ----- | ------------------------------------------------------------- |
| `100` | Request successful.                                           |
| `101` | Resource created successfully (e.g. address book or contact). |

### Success example

```json theme={null}
HTTP/1.1 200 OK
{
  "data": {
    "id": "60e99589eeadc6338b16cb42",
    "message": "Contact added successfully",
    "status": "true"
  }
}
```

***

## Client errors (4XX)

| Code / HTTP        | Description                                                          |
| ------------------ | -------------------------------------------------------------------- |
| `400`              | Bad request — invalid input, malformed payload, or validation error. |
| `401`              | Invalid mobile number format.                                        |
| `402`              | Missing required parameters.                                         |
| `403`              | Invalid query parameters (pagination, filters, etc.).                |
| `HTTP 401` / `120` | Invalid authentication parameters (`api_key` or `secret_key`).       |
| `HTTP 403` / `403` | Forbidden action (e.g. attempting a restricted operation).           |
| `HTTP 404` / `404` | Resource not found — address book or contact does not exist.         |
| `HTTP 409` / `409` | Conflict — duplicate address book or contact already exists.         |
| `HTTP 409` / `410` | Operation not allowed (e.g. deleting the Default address book).      |
| `HTTP 422` / `422` | Validation failed for one or more fields.                            |

***

## Server errors (5XX)

| Code / HTTP        | Description                      |
| ------------------ | -------------------------------- |
| `HTTP 500` / `500` | Internal server error.           |
| `HTTP 503` / `503` | Service temporarily unavailable. |

***

## Authentication error example

```json theme={null}
HTTP/1.1 401 Unauthorized
{
  "code": 120,
  "message": "Invalid Authorization Parameters"
}
```

***

## Conflict error example

Returned when creating a contact that already exists in the address book (`POST /contacts`):

```json theme={null}
HTTP/1.1 409 Conflict
{
  "data": {
    "message": "Contact already exists",
    "status": "false"
  }
}
```

***

## Not found error example

Returned when the address book or contact does not exist:

```json theme={null}
HTTP/1.1 404 Not Found
{
  "data": {
    "message": "Addressbook Not Found",
    "status": "false"
  }
}
```

***

## Bad request error example

Returned when a mobile number is invalid (`POST /contacts`, `PUT /contacts/{contact_id}`):

```json theme={null}
HTTP/1.1 400 Bad Request
{
  "status": 400,
  "message": "Invalid Mobile Number"
}
```

***

## Related

* [Authentication](/guides/contact/authentication) — API credentials and access tokens
* [Best practices](/guides/contact/best-practices) — organizing address books and contacts