Error Handling Guidelines

Standards for handling exceptions, HTTP status codes, and error payloads across MetaPilot API.

Standard HTTP Status Code Rules

Code	Meaning	Usage in MetaPilot
200	OK	Successful GET, PUT, PATCH operations
201	Created	Successful POST creation (User, Tenant, Campaign)
204	No Content	Successful DELETE operations
400	Bad Request	Validation errors, invalid payload format
401	Unauthorized	Missing or expired JWT access token
403	Forbidden	Valid JWT, but insufficient role permissions
404	Not Found	Target object does not exist or belongs to another tenant
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unhandled server exception (logged with stack trace)

All DRF error responses return a uniform JSON format:

json

{
  "error": "Short human-readable summary",
  "code": "SPECIFIC_ERROR_CODE",
  "details": {
    "field_name": ["Validation error message"]
  }
}

Catch Specific Exceptions: Always catch specific exceptions (
```
ValueError
```
,
```
InvalidToken
```
,
```
psycopg2.OperationalError
```
) rather than bare
```
except:
```
.
Log Stack Traces: Log full exception tracebacks before returning 500 error responses:
python
```
logger.error(f"Failed to process campaign broadcast: {exc}", exc_info=True)
```
Environment Safety in Dev: In
```
DEBUG=True
```
mode, provide fallback defaults for missing dev configurations (such as standard dev Fernet keys) while enforcing strict validation in production.