Table of Contents

Error Codes

EMAIL - Email sending and credit checking operations
EMAIL OTP - OTP send and verify operations
ATTACHMENT - File attachment management operations

Additional Information

Response Format - API response structure
Error Details - Detailed error explanations

📝 Response Format

Standard Endpoints (Non-OTP)

Response format for general endpoints (except OTP endpoints):

{
  statusCode: number,        // HTTP status code
  timestamp: string,         // ISO 8601 format (UTC)
  message: string,           // Error message
  required?: string[]        // Optional: validation errors array
}

Example:

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Email template not found.",
  "required": [
    "mail_from must be a non-empty object"
  ]
}

OTP Endpoints

Response format for OTP endpoints (/email/v1/otp/*):

{
  code: string,              // Error code
  message: string            // Error message
}

Example:

{
  "code": "invalid_request",
  "message": "Invalid request"
}

Success Response

Response format for successful email sending:

{
  message_id: string,        // UUID of the email transaction
  credit_type: string,      // "EMAIL"
  credit_remain: number,    // Remaining credit
  credit_used: number       // Credit used for this transaction
}

EMAIL

Errors for email sending and credit checking operations (/email/v1/send_template, /email/v1/credit)

Error Response

Status Code	Code	Message
400	ERROR_CALLBACK_URL	Callback Url is invalid.
400	ERROR_CALLBACK_METHOD	You can choose callback method are GET, POST or PUT method.
400	ERROR_EMAIL_TEMPLATE_NOT_READY	Email template is not ready.
400	ERROR_RECIPIENT_UNSUBSCRIBED	Recipient has unsubscribed from emails.
400	ERROR_INVALID_FILE	Invalid file.
400	ERROR_TOTAL_FILE_LIMIT_EXCEED	Total file limit exceeded. (Max 5 files).
400	ERROR_MAX_FILE_SIZE_EXCEED	Max file size limit exceeded (5MB).
400	ERROR_FAILED_URL_ATTACHMENT	Failed to get URL attachment.
400	-	to email is invalid
400	-	payload must be JSON object
400	-	All properties in payload must be strings
400	-	Keyword spam detected!
401	ERROR_AUTHENTICATION_FAILED	Authentication failed.
402	ERROR_INSUFFICIENT_CREDIT	Insufficient credit.
402	ERROR_EXPIRED_CREDIT	Expired credit.
403	ERROR_API_KEY_SUSPENDED	This API key has been suspended.
403	ERROR_IP_NOT_ALLOWED	This IP has been suspended.
404	ERROR_EMAIL_SENDER_NOT_FOUND	Sender not found.
404	ERROR_EMAIL_TEMPLATE_NOT_FOUND	Email template not found.
429	-	Rate limit exceeded
500	-	Internal server error
503	-	Service unavailable

Note: Errors with - in Code column indicate that the error code is not explicitly defined, only the message is returned.

EMAIL OTP

Errors for OTP send and verify operations (/email/v1/otp/send, /email/v1/otp/verify)

Error Response

Status Code	Code	Message
400	invalid_request	Invalid email template
400	invalid_request	Invalid OTP
400	invalid_request	Invalid request
401	unauthorized	Unauthorized
402	error_insufficient_credit	Error insufficient credit
404	not_found	Not found
500	Internal_server_error	Internal server error

Note: OTP endpoints use a different error format with code and message fields instead of statusCode and message.

ATTACHMENT

Errors for File attachment management operations (/email/v1/email-attachment/*)

Error Response

Status Code	Code	Message
400	ATTACHMENT_NOT_FOUND	Attachment not found
400	ERROR_FILE_NOT_ALLOWED	File is not allowed!
400	-	No file uploaded
401	ERROR_AUTHENTICATION_FAILED	Authentication failed.
403	ERROR_API_KEY_SUSPENDED	This API key has been suspended.
403	ERROR_IP_NOT_ALLOWED	This IP has been suspended.
404	ATTACHMENT_NOT_FOUND	Attachment not found
413	-	Payload Too Large
415	-	Files are not allowed!

File Limits:

Maximum files: 5 files per email
Maximum file size: 5MB per file
Total size: Combined size should not exceed reasonable limits

Supported File Types:

Documents: .txt, .csv, .doc, .docx, .xls, .xlsx, .pdf
Images: .png, .jpeg, .jpg, .gif
Videos: .mov

Error Details

Authentication & Authorization

401 Unauthorized

Standard Format:

{
  "statusCode": 401,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Authentication failed."
}

OTP Format:

{
  "code": "unauthorized",
  "message": "Unauthorized"
}

Solution:

Verify API key and API secret
Check Basic Auth header format: Authorization: Basic <base64(api-key:api-secret)>
Verify that the API key is still active

403 Forbidden

Example Response:

{
  "statusCode": 403,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "This API key has been suspended."
}

Solution:

Contact support to reactivate the API key or IP

Credit & Payment

402 Payment Required

Standard Format:

{
  "statusCode": 402,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Insufficient credit."
}

OTP Format:

{
  "code": "error_insufficient_credit",
  "message": "error insufficient credit"
}

Solution:

Add credit
Check credit expiration date

Resource Not Found

404 Not Found

Standard Format:

{
  "statusCode": 404,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Email template not found."
}

OTP Format:

{
  "code": "not_found",
  "message": "Not found"
}

Solution:

Verify template UUID or sender email
Check sender approval status
Verify template ownership

Validation Errors

400 Bad Request

Example Response (Validation Error):

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Validation failed",
  "required": [
    "mail_from must be a non-empty object",
    "mail_to must be a non-empty object",
    "subject must be longer than or equal to 1 characters"
  ]
}

Example Response (Invalid Email):

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "to email is invalid"
}

OTP Format:

{
  "code": "invalid_request",
  "message": "Invalid request"
}

Solution:

Verify request payload structure
Check email format
Verify payload properties (all must be strings)
Check callback URL format and accessibility

File & Attachment Errors

Example Response:

{
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Total file limit exceeded. (Max 5 files)."
}

Solution:

Reduce the number of files to a maximum of 5 files
Reduce file size to a maximum of 5MB per file
Check allowed file extensions
Verify URL accessibility (for URL attachments)

Rate Limiting

429 Too Many Requests

Example Response:

{
  "statusCode": 429,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Rate limit exceeded"
}

Retry Strategy:

⏱️ Wait before retrying
📉 Reduce request rate
🔄 Use exponential backoff

Server Errors

500 Internal Server Error

Standard Format:

{
  "statusCode": 500,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Internal server error"
}

OTP Format:

{
  "code": "Internal_server_error",
  "message": "Internal server error"
}

Retry Strategy:

✅ 5xx Errors: Retry with exponential backoff
❌ 4xx Errors: Don't retry (except 429)

503 Service Unavailable

Example Response:

{
  "statusCode": 503,
  "timestamp": "2024-01-15T10:30:00.000Z",
  "message": "Service unavailable"
}