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:

json

{
  "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 1,000)
`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`	`400`	Missing Idempotency-Key header (required for all refund requests)
`REFUND_005`	`409`	Invalid state transition (e.g., cannot cancel a processing/completed refund)
`REFUND_006`	`409`	Transaction already refunded
`REFUND_007`	`422`	Amount exceeds original transaction
`REFUND_008`	`503`	Payment provider unavailable
`REFUND_009`	`422`	Invalid beneficiary account details

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
`SMS_007`	`403`	SMS permissions not granted on device

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
`VPN_009`	`403`	VPN permission rejected by user

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

Webhook Errors (WEBHOOK_)

Code	HTTP	Description
`WEBHOOK_001`	`400`	Invalid webhook URL
`WEBHOOK_002`	`401`	Invalid signature verification
`WEBHOOK_003`	`404`	Webhook not found
`WEBHOOK_004`	`422`	Unsupported event type

General & SDK Errors (GEN_)

Code	HTTP	Description
`GEN_001`	`403`	SDK integration required for this feature
`GEN_002`	`403`	Missing required device permissions

Idempotency Keys

Certain endpoints require an Idempotency-Key header to prevent duplicate operations. This is critical for financial operations like refunds.

Property	Value
Header Name	`Idempotency-Key`
Format	UUID v4 recommended (e.g., `550e8400-e29b-41d4-a716-446655440000`)
Validity Period	24 hours from first use
Required Endpoints	`POST /refund/request`,`Webhooks (X-DGuard-Event-ID)`

bash

# Example request with Idempotency-Key
curl -X POST https://api.dguard.ai/v1/refund/request \
  -H "Authorization: Bearer {access_token}" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"transaction_id": "txn_abc123", ...}'

Important: If you retry a request with the same Idempotency-Key within 24 hours, the API returns the original response instead of creating a duplicate. This ensures safe retries after network failures.

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.
•Always include Idempotency-Key header for refund requests to enable safe retries.