Table of Contents

Error Codes

EMAIL - การส่งอีเมลและการจตรวจเครดิตคงเหลือ
EMAIL OTP - การส่งและยืนยัน OTP
ATTACHMENT - การจัดการไฟล์แนบ

Additional Information

Response Format - โครงสร้าง response ของ API
Error Details - คำอธิบาย error แบบละเอียด

📝 Response Format

Standard Endpoints (Non-OTP)

Response format สำหรับ endpoints ทั่วไป (ยกเว้น 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 สำหรับ OTP endpoints (/email/v1/otp/*):

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

Example:

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

Success Response

Response format สำหรับการส่งอีเมลสำเร็จ:

{
  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 สำหรับการส่ง email และการตรวจเครดิตคงเหลือ (/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 สำหรับ 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 สำหรับ 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"
}

วิธีแก้ไข:

ตรวจสอบ API key และ API secret
ตรวจสอบ Basic Auth header format: Authorization: Basic <base64(api-key:api-secret)>
ตรวจสอบว่า API key ยังใช้งานได้

403 Forbidden

Example Response:

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

วิธีแก้ไข:

ติดต่อ support เพื่อเปิดใช้งาน API key หรือ 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"
}

วิธีแก้ไข:

เติมเครดิตเพิ่ม
ตรวจสอบ 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"
}

วิธีแก้ไข:

ตรวจสอบ template UUID หรือ sender email
ตรวจสอบสถานะ approval ของ sender
ตรวจสอบ 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"
}

วิธีแก้ไข:

ตรวจสอบ request payload structure
ตรวจสอบ email format
ตรวจสอบ payload properties (ต้องเป็น string ทั้งหมด)
ตรวจสอบ callback URL format และ accessibility

File & Attachment Errors

Example Response:

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

วิธีแก้ไข:

ลดจำนวนไฟล์ให้เหลือไม่เกิน 5 ไฟล์
ลดขนาดไฟล์ให้ไม่เกิน 5MB ต่อไฟล์
ตรวจสอบ file extension ที่อนุญาต
ตรวจสอบ URL accessibility (สำหรับ URL attachment)

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"
}