Error Codes & Troubleshooting

For detailed error response formats across Django DRF and NestJS, see Error Responses.

Standard Error Format

All ZoneVast services return errors in a consistent format:

{
  "detail": "Human-readable message",
  "code": "error_code"
}

For validation errors:

{
  "field_name": ["Error message for this field"],
  "other_field": ["Another error"]
}

HTTP Status Codes

Status	Meaning	Common Cause
200	Success	Request completed
201	Created	Resource created successfully
204	No Content	Deleted successfully
400	Bad Request	Invalid input data
401	Unauthorized	Missing or invalid token
403	Forbidden	Token valid but insufficient permissions
404	Not Found	Resource does not exist
409	Conflict	Duplicate resource
429	Too Many Requests	Rate limit exceeded
500	Server Error	Backend issue (check logs)

Common Errors

Authentication Errors

Error	Cause	Fix
token_not_valid	Expired or malformed JWT	Refresh token or re-login
Authentication credentials were not provided	Missing Authorization header	Add Bearer token
User is inactive	Account not activated	Verify OTP or contact admin
No active account found	Wrong credentials	Check username/password

Project Errors

Error	Cause	Fix
Project not found	Invalid X-Project-ID	Verify project ID
Project membership required	User not in project	Add user to project

Rate Limiting

Error	Cause	Fix
Request was throttled	Too many requests	Wait available_in seconds
OTP cooldown active	OTP sent too recently	Wait for cooldown period

Debugging Checklist

Request Fails with 401

1. Check token is present in Authorization: Bearer {token}
2. Verify token is not expired (check exp claim)
3. Try refreshing the token
4. Ensure you are using the correct auth service endpoint

Request Fails with 403

1. Verify X-Project-ID matches the token's project
2. Check user role has required permissions
3. Confirm the endpoint supports the user's role

Request Fails with 400

1. Check request body matches expected schema
2. Verify all required fields are present
3. Ensure field types are correct (string vs number)
4. Check for extra/unexpected fields

Request Fails with 500

1. Check AWS Lambda logs: zappa tail dev
2. Verify database connectivity
3. Check for recent deployments
4. Test with a minimal request body

Viewing Backend Logs

Django Services (Zappa)

cd /path/to/service
zappa tail dev --since 5m  # Last 5 minutes
zappa tail dev --filter "ERROR"  # Only errors

NestJS Services (AWS Lambda)

aws logs tail /aws/lambda/service-name-dev --region eu-central-1

Testing with curl

Verbose Output

curl -v https://test.zonevast.com/api/v1/auth/auth/user/ \
  -H "Authorization: Bearer TOKEN"

Pretty JSON Output

curl -s https://test.zonevast.com/api/v1/auth/auth/user/ \
  -H "Authorization: Bearer TOKEN" | python3 -m json.tool

Save Response Headers

curl -i https://test.zonevast.com/api/v1/auth/auth/user/ \
  -H "Authorization: Bearer TOKEN"