Error Reference

Complete reference for all error types and codes in the MsGine SDK.

MsGineError

The base error class for all SDK-related errors.

class MsGineError extends Error {
  name: string
  message: string
  statusCode: number
  code: string
  details?: Record<string, any>
}

Error Codes

Authentication Errors

unauthorized

Status Code: 401

Description: Invalid or missing API token.

Example:

{
  code: 'unauthorized',
  message: 'Invalid API token',
  statusCode: 401
}

Solutions:

• Verify your API token is correct
• Check that the token hasn't been revoked
• Ensure the token is properly loaded from environment variables

forbidden

Status Code: 403

Description: Insufficient permissions for the requested operation.

Example:

{
  code: 'forbidden',
  message: 'Insufficient permissions',
  statusCode: 403
}

Validation Errors

invalid_phone_number

Status Code: 400

Description: Phone number is not in valid E.164 format.

Example:

{
  code: 'invalid_phone_number',
  message: 'The phone number must be in E.164 format',
  statusCode: 400,
  details: {
    field: 'to',
    value: '0701234567',
    expected: '+[country code][number]'
  }
}

Solutions:

• Use E.164 format: +[country code][number]
• Example: +256701521269 (not 0701521269)
• Include the + prefix and country code

invalid_message

Status Code: 400

Description: Message content is invalid or too long.

Example:

{
  code: 'invalid_message',
  message: 'Message exceeds maximum length of 1600 characters',
  statusCode: 400,
  details: {
    field: 'message',
    maxLength: 1600,
    actualLength: 1850
  }
}

Solutions:

• Keep messages under 1600 characters
• Split long messages into multiple parts
• Remove unnecessary content

invalid_sender_id

Status Code: 400

Description: Sender ID format is invalid.

Example:

{
  code: 'invalid_sender_id',
  message: 'Sender ID must be alphanumeric and max 11 characters',
  statusCode: 400,
  details: {
    field: 'from',
    value: 'My Long Company Name',
    maxLength: 11
  }
}

Solutions:

• Use alphanumeric characters only
• Keep sender ID under 11 characters
• Avoid special characters and spaces

Rate Limiting Errors

rate_limit_exceeded

Status Code: 429

Description: Too many requests sent in a given time period.

Example:

{
  code: 'rate_limit_exceeded',
  message: 'Too many requests. Please try again later.',
  statusCode: 429,
  details: {
    retryAfter: 60,
    limit: 100,
    period: '1 minute'
  }
}

Solutions:

• Wait for the duration specified in retryAfter (seconds)
• Implement request queuing
• Upgrade to a higher-tier plan for increased limits
• The SDK automatically retries with exponential backoff

Account Errors

insufficient_balance

Status Code: 402

Description: Account balance is too low to complete the operation.

Example:

{
  code: 'insufficient_balance',
  message: 'Insufficient account balance',
  statusCode: 402,
  details: {
    balance: 0.50,
    required: 1.25,
    currency: 'USD'
  }
}

Solutions:

• Add funds to your account
• Contact support for billing assistance
• Check pricing for your destination

Server Errors

internal_error

Status Code: 500

Description: An unexpected error occurred on the server.

Example:

{
  code: 'internal_error',
  message: 'An internal server error occurred',
  statusCode: 500
}

Solutions:

• The SDK will automatically retry
• If the issue persists, contact support
• Check the status page for service incidents

service_unavailable

Status Code: 503

Description: The service is temporarily unavailable.

Example:

{
  code: 'service_unavailable',
  message: 'Service temporarily unavailable',
  statusCode: 503,
  details: {
    retryAfter: 120
  }
}

Solutions:

• Wait and retry after the specified duration
• The SDK automatically retries with backoff
• Check the status page for maintenance windows

Network Errors

network_error

Description: Network connectivity issue or timeout.

Example:

{
  code: 'network_error',
  message: 'Network request failed',
  statusCode: 0,
  details: {
    originalError: 'ETIMEDOUT'
  }
}

Solutions:

• Check your internet connection
• Verify firewall settings allow HTTPS requests
• Increase the timeout setting if needed
• The SDK automatically retries network errors

timeout_error

Description: Request exceeded the configured timeout.

Example:

{
  code: 'timeout_error',
  message: 'Request timed out after 30000ms',
  statusCode: 0,
  details: {
    timeoutMs: 30000
  }
}

Solutions:

• Increase the timeout in client configuration
• Check network connectivity
• Contact support if timeouts persist

Error Handling Patterns

Check Error Type

import { MsGineError } from '@msgine/sdk'

try {
  await client.sendSms({ to: phone, message: text })
} catch (error) {
  if (error instanceof MsGineError) {
    console.error('API Error:', error.code, error.message)
  } else {
    console.error('Unexpected error:', error)
  }
}

Handle Specific Errors

try {
  await client.sendSms({ to: phone, message: text })
} catch (error) {
  if (error instanceof MsGineError) {
    switch (error.code) {
      case 'invalid_phone_number':
        console.error('Phone validation failed:', error.details)
        break
      case 'insufficient_balance':
        console.error('Balance too low:', error.details)
        break
      case 'rate_limit_exceeded':
        console.error('Rate limited, retry after:', error.details.retryAfter)
        break
      default:
        console.error('Unknown error:', error.message)
    }
  }
}

Retry on Specific Errors

async function sendWithRetry(to: string, message: string, retries = 3) {
  try {
    return await client.sendSms({ to, message })
  } catch (error) {
    if (error instanceof MsGineError && error.code === 'rate_limit_exceeded' && retries > 0) {
      const delay = error.details?.retryAfter * 1000 || 60000
      await new Promise(resolve => setTimeout(resolve, delay))
      return sendWithRetry(to, message, retries - 1)
    }
    throw error
  }
}

Next Steps

• Error Handling Guide - Best practices for handling errors
• API Reference - Complete client documentation
• Type Reference - Complete type definitions