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

# Errors

> How the Sotto API reports errors.

The Sotto API uses conventional HTTP status codes to indicate the success or
failure of a request.

| Code  | Meaning                                                               |
| ----- | --------------------------------------------------------------------- |
| `200` | OK — the request succeeded.                                           |
| `201` | Created — a new resource was created.                                 |
| `400` | Bad Request — the request was invalid.                                |
| `401` | Unauthorized — authentication failed.                                 |
| `404` | Not Found — the requested resource does not exist.                    |
| `409` | Conflict — a resource with the same unique identifier already exists. |
| `422` | Validation Error — one or more fields failed validation.              |
| `500` | Internal Server Error — something went wrong on our end.              |

## Error format

Errors return a JSON body with a `detail` object containing a machine-readable
`type` and a human-readable `msg`:

```json theme={"dark"}
{
  "detail": {
    "type": "error_type",
    "msg": "Human-readable error message"
  }
}
```

## Examples

<AccordionGroup>
  <Accordion title="401 — Authentication failed">
    ```json theme={"dark"}
    {
      "detail": {
        "type": "not_authenticated",
        "msg": "HMAC signature verification failed"
      }
    }
    ```
  </Accordion>

  <Accordion title="404 — User not found">
    ```json theme={"dark"}
    {
      "detail": {
        "type": "user_not_found",
        "msg": "User with ID [1] not found."
      }
    }
    ```
  </Accordion>

  <Accordion title="409 — Duplicate entry">
    ```json theme={"dark"}
    {
      "detail": {
        "type": "duplicate_record_found",
        "msg": "Duplicate entry for '+15551234567'"
      }
    }
    ```
  </Accordion>

  <Accordion title="422 — Invalid phone number">
    ```json theme={"dark"}
    {
      "detail": {
        "type": "invalid_phone_number",
        "msg": "Invalid phone number [555-123-4567] provided."
      }
    }
    ```
  </Accordion>

  <Accordion title="500 — Internal server error">
    ```json theme={"dark"}
    {
      "detail": {
        "type": "UNCAUGHT_ERROR",
        "msg": "Internal server error"
      }
    }
    ```
  </Accordion>
</AccordionGroup>