Dovodi_Backend/apps/account/API_ERRORS.md

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:

{
    "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.