# Account API Error Documentation

This document lists the potential errors returned by the registration and account endpoints in the `account` app, including the error messages and the reasons they occur.

## Common Error Format
All errors follow a standardized JSON structure defined in the project's custom exception handler:

```json
{
    "status": "error",
    "code": "validation_error",
    "status_code": 400,
    "message": "There were validation errors.",
    "errors": [
        {
            "field": "email",
            "message": "This email is already registered."
        }
    ]
}
```

---

## 1. Registration Endpoints
**Endpoints:** `POST /register/`, `POST /web/register/`

| Error Message | Field | Reason |
| :--- | :--- | :--- |
| `This email is already registered.` | `email` | The email address is already associated with an existing account. |
| `Enter a valid email address.` | `email` | The provided email format is incorrect (e.g., missing `@` or domain). |
| `This field is required.` | Multiple | A mandatory field (like `email`, `fullname`, or `password` for web) was missing from the request. |
| `This password is too short...` | `password` | (Web only) The password does not meet Django's security requirements (length, complexity). |

---

## 2. Verification Endpoint
**Endpoint:** `POST /verify/`

| Error Message | Field | Reason |
| :--- | :--- | :--- |
| `Verification data not found or expired.` | `code` | There is no active registration session in Redis for this email. Usually occurs if the user waits too long or tries to verify an email they didn't just register. |
| `The verification code has expired.` | `code` | The OTP code's Time-To-Live (TTL) has passed (usually 5-10 minutes). |
| `code notfound` | `code` | The provided OTP code is incorrect. |
| `enter code numeric` | `code` | The provided code contains non-numeric characters. |

---

## 3. Authentication & Login
**Endpoint:** `POST /login/`

| Error Message | Field | Reason |
| :--- | :--- | :--- |
| `user not exists with this email` | `email` | No user account was found with the provided email address. |
| `password is incorrect` | `password` | The email is correct, but the password does not match the record in the database. |
| `Unable to log in with provided credentials.` | `non_field_errors` | Catch-all for failed authentication attempts. |

---

## 4. Guest Account Endpoints
**Endpoints:** `POST /guest/`, `POST /web/guest/`

| Error Message | Field | Reason |
| :--- | :--- | :--- |
| `Device ID is required for guest users.` | `device_id` | (Mobile) The unique device identifier was not sent in the request. |
| `Device ID is required for web guest users.` | `device_id` | (Web) Internal error where the identifier generation failed. |

---

## 5. Token Exchange (Mobile Auth)
**Endpoint:** `POST /exchange-token/`

| Error Message | Status Code | Reason |
| :--- | :--- | :--- |
| `توکن ارسال نشده است` | 400 | The `temp_token` was missing from the request body. |
| `توکن نامعتبر یا منقضی شده است` | 404 | The temporary token from the login redirect has expired or is invalid. |
| `توکن نامعتبر است` | 400 | The token exists but is missing required session data (`user_id`). |
| `کاربر یافت نشد` | 404 | The user account associated with the token has been deleted. |

---

## 6. Profile & Password Management
**Endpoints:** `GET/PUT /profile/update/`, `POST /reset/`

| Error Message | Status Code | Reason |
| :--- | :--- | :--- |
| `Authentication credentials were not provided.` | 401 | Missing or incorrect `Authorization: Token <key>` header. |
| `Invalid token.` | 401 | The provided token has expired or belongs to a deleted user. |
| `This password is too common.` | 400 | Password reset failed because the new password is too simple. |
| `You do not have permission...` | 403 | The user's account has been deactivated (inactive). |

---

## 7. Account Deletion
**Endpoint:** `DELETE /profile/delete/`

| Error Message | Status Code | Reason |
| :--- | :--- | :--- |
| `Unable to log in with provided credentials.` | 204 | Attempted to delete the protected primary administrator account (`admin@gmail.com`). |
| `User does not exist.` | 404 | The system could not find the user object to perform the soft-delete. |