Error Codes Reference - SMSDESK Developer Portal

Centralized Error Handling: All SMSDESK APIs and SMPP operations use standardized error codes for consistent error handling and debugging.

Overview

SMSDESK uses a centralized error code system across all APIs and SMPP operations. Each error code provides:

Unique Code: A unique identifier for the error (e.g., AUTH_001, ESME_RTHROTTLED)
Type: Error severity (Error, Warning, Information)
Category: Error classification (Authentication, Validation, SMPP, etc.)
Message: Human-readable error message
Description: Detailed explanation and resolution steps

Error Response Format

{
  "success": false,
  "error": {
    "code": "AUTH_001",
    "type": "Error",
    "category": "Authentication",
    "message": "Invalid API key",
    "description": "The provided API key is invalid or has been revoked. Please check your API key in the web portal."
  }
}

Backend Error Codes

Error codes used by HTTP APIs (SMS API, USSD API, Backend API)

Authentication Errors (AUTH_xxx)

Code	Type	Message	Description
`AUTH_001`	Error	Invalid API key	The provided API key is invalid or has been revoked
`AUTH_002`	Error	Missing API key	No API key provided in the Authorization header
`AUTH_003`	Error	Expired API key	The API key has expired and needs to be renewed
`AUTH_004`	Error	Insufficient permissions	Your account does not have permission for this operation
`AUTH_005`	Error	Account suspended	Your account has been suspended. Contact support.
`AUTH_006`	Error	Invalid credentials	Username or password is incorrect

Validation Errors (VAL_xxx)

Code	Type	Message	Description
`VAL_001`	Error	Missing required field	A required field is missing from the request
`VAL_002`	Error	Invalid phone number	The phone number format is invalid
`VAL_003`	Error	Message too long	The message exceeds the maximum allowed length
`VAL_004`	Error	Invalid date format	The date/time format is invalid. Use ISO 8601 format.
`VAL_005`	Error	Invalid parameter value	One or more parameters have invalid values

System Errors (SYS_xxx)

Code	Type	Message	Description
`SYS_001`	Error	Internal server error	An unexpected error occurred. Please try again later.
`SYS_002`	Error	Database error	A database error occurred. Please contact support.
`SYS_003`	Warning	Service temporarily unavailable	The service is temporarily unavailable. Please retry.
`SYS_004`	Error	Rate limit exceeded	Too many requests. Please slow down.

SMPP Protocol Error Codes

Standard SMPP v3.4 protocol error codes (ESME_xxx)

SMPP Compliance: These error codes follow the SMPP v3.4 specification and are used by the SMPP server for protocol-level errors.

Common SMPP Errors

Code	Hex Value	Message	Action
`ESME_ROK`	0x00000000	Success	Continue processing
`ESME_RTHROTTLED`	0x00000058	Throttling error	RETRY with delay
`ESME_RMSGQFUL`	0x00000014	Message queue full	RETRY with delay
`ESME_RINVDSTADR`	0x0000000B	Invalid destination address	Check number format
`ESME_RINVSRCADR`	0x0000000A	Invalid source address	Check sender ID
`ESME_RBINDFAIL`	0x0000000D	Bind failed	Check credentials
`ESME_RINVPASWD`	0x0000000E	Invalid password	Verify password
`ESME_RSUBMITFAIL`	0x00000045	Submit failed	Check message format

View Complete SMPP Error Code List

SMPP Custom Error Codes

Application-specific error codes for SMPP operations

Connection Errors (CONN_xxx)

Code	Type	Message	Retry?
`CONN_001`	Error	Connection failed	✓ Yes
`CONN_002`	Error	Connection timeout	✓ Yes
`CONN_003`	Error	Connection lost	✓ Yes
`CONN_004`	Error	Bind failed	✗ No

Submission Errors (SUB_xxx)

Code	Type	Message	Retry?
`SUB_001`	Error	Submit failed	✓ Yes
`SUB_002`	Error	Invalid message format	✗ No
`SUB_003`	Error	Message too long	✗ No
`SUB_007`	Error	Insufficient credit	✗ No

Error Types

Type	Description	HTTP Status	Action
Error	Critical error that prevents operation completion	400, 401, 403, 500	Fix the issue before retrying
Warning	Non-critical issue that may affect operation	200, 429	Review and consider retry
Information	Informational message about operation status	200	No action required

Best Practices

Error Handling

// Example error handling in JavaScript
try {
    const response = await fetch('/sms/3/messages', {
        method: 'POST',
        headers: {
            'Authorization': 'YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({ /* ... */ })
    });
    
    const data = await response.json();
    
    if (!data.success) {
        const error = data.error;
        console.error(`Error ${error.code}: ${error.message}`);
        
        // Handle specific error codes
        switch (error.code) {
            case 'AUTH_001':
                // Invalid API key - update credentials
                break;
            case 'VAL_002':
                // Invalid phone number - validate input
                break;
            case 'SYS_004':
                // Rate limit - implement backoff
                await sleep(1000);
                retry();
                break;
            default:
                // Generic error handling
                console.error(error.description);
        }
    }
} catch (err) {
    console.error('Network error:', err);
}

Retry Logic

Retriable Errors: CONN_xxx, SUB_001, SYS_003, ESME_RTHROTTLED
Non-Retriable: AUTH_xxx, VAL_xxx, ESME_RINVDSTADR
Backoff Strategy: Exponential backoff for rate limits
Max Retries: Limit to 3 attempts for most errors

Logging

Always log error codes for debugging
Include error descriptions in logs
Track error frequency for monitoring
Alert on critical errors (AUTH_005, SYS_002)

Need Help? If you encounter an error code not listed here or need assistance, please contact support with the error code and request details.