Error Codes

All DGuard API errors follow a consistent format with specific error codes per module. Use these codes to handle errors gracefully in your application.

Error Response Format

All error responses include the following structure:

{
  "error_code": "FRAUD_001",
  "message": "Transaction not found",
  "details": {
    "transaction_id": "txn_123"
  },
  "timestamp": "2025-01-14T18:00:00Z",
  "request_id": "req_abc123"
}

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or expired token
`403`	Forbidden - Insufficient permissions
`404`	Not Found
`409`	Conflict - Duplicate resource
`422`	Unprocessable Entity - Validation error
`429`	Too Many Requests - Rate limited
`500`	Internal Server Error
`503`	Service Unavailable
`504`	Gateway Timeout

Authentication Errors (AUTH_)

Code	HTTP	Description
`AUTH_001`	`401`	Invalid credentials
`AUTH_002`	`401`	Token expired
`AUTH_003`	`403`	Insufficient scope
`AUTH_004`	`429`	Too many login attempts

Fraud Detection Errors (FRAUD_)

Code	HTTP	Description
`FRAUD_001`	`400`	Invalid transaction data
`FRAUD_002`	`400`	Too many transactions in batch (max 100)
`FRAUD_003`	`404`	Transaction not found
`FRAUD_004`	`422`	Unsupported transaction type
`FRAUD_005`	`429`	Rate limit exceeded
`FRAUD_006`	`500`	ML model error

Refund Errors (REFUND_)

Code	HTTP	Description
`REFUND_001`	`400`	Invalid refund request
`REFUND_002`	`404`	Original transaction not found
`REFUND_003`	`404`	Refund not found
`REFUND_004`	`409`	Duplicate refund (idempotency key)
`REFUND_005`	`409`	Transaction already refunded
`REFUND_006`	`400`	Cannot cancel (already processed)
`REFUND_007`	`422`	Amount exceeds original transaction
`REFUND_008`	`503`	Payment provider unavailable

Email Protection Errors (EMAIL_)

Code	HTTP	Description
`EMAIL_001`	`400`	Invalid email content
`EMAIL_002`	`400`	Missing required fields
`EMAIL_003`	`404`	Account not found
`EMAIL_004`	`409`	Account already connected
`EMAIL_005`	`401`	OAuth authorization failed
`EMAIL_006`	`429`	Rate limit exceeded
`EMAIL_007`	`500`	ML analysis error

URL Scanning Errors (URL_)

Code	HTTP	Description
`URL_001`	`400`	Invalid URL format
`URL_002`	`400`	Too many URLs in batch (max 100)
`URL_003`	`422`	URL not accessible
`URL_004`	`429`	Rate limit exceeded
`URL_005`	`504`	Scan timeout

SMS Protection Errors (SMS_)

Code	HTTP	Description
`SMS_001`	`400`	Empty or invalid message
`SMS_002`	`400`	Too many messages in batch (max 100)
`SMS_003`	`404`	Analysis not found
`SMS_004`	`422`	Unsupported platform
`SMS_005`	`429`	Rate limit exceeded
`SMS_006`	`500`	ML analysis error

VPN Service Errors (VPN_)

Code	HTTP	Description
`VPN_001`	`429`	Device limit reached (max 2)
`VPN_002`	`503`	No slots available in pool
`VPN_003`	`503`	Server under maintenance
`VPN_004`	`404`	Server not found
`VPN_005`	`404`	Session not found
`VPN_006`	`400`	Device already connected
`VPN_007`	`408`	Heartbeat timeout
`VPN_008`	`500`	OpenVPN configuration error

Dark Web Monitoring Errors (DARKWEB_)

Code	HTTP	Description
`DARKWEB_001`	`400`	Invalid email format
`DARKWEB_002`	`404`	Monitor not found
`DARKWEB_003`	`409`	Email already being monitored
`DARKWEB_004`	`429`	Too many queries
`DARKWEB_005`	`503`	Verification service unavailable

Notification Errors (NOTIF_)

Code	HTTP	Description
`NOTIF_001`	`400`	Invalid push token
`NOTIF_002`	`404`	Device not registered
`NOTIF_003`	`404`	Notification not found
`NOTIF_004`	`404`	User not found
`NOTIF_005`	`422`	Unsupported platform
`NOTIF_006`	`422`	Invalid category
`NOTIF_007`	`429`	Rate limit exceeded
`NOTIF_008`	`503`	Push service unavailable

Best Practices

•Always check the error_code field in error responses for precise error handling.
•Use the request_id from error responses when contacting support for faster resolution.
•Implement exponential backoff for 429 (Rate Limited) and 503 (Service Unavailable) errors.
•Log all error responses with their request_id for debugging and monitoring.