Error Reference

Complete reference for all error codes and status codes returned by the TXTLINK API. Use this guide to handle errors gracefully in your application.

Error Response Format

All error responses follow a consistent format:

json

{
  "error": "Insufficient SMS credits",
  "errorCode": "INSUFFICIENT_CREDITS",
  "message": "Your account does not have enough credits to send this message"
}

Response Fields

error - Human-readable error message
errorCode - Machine-readable error code for programmatic handling
message - Additional context (optional)

Error Handling

Always check the HTTP status code and handle errors appropriately:

javascript

// JavaScript/Node.js
try {
  const response = await fetch('https://api.txtlink.com/v1/sms/send', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      to: '+254712345678',
      message: 'Hello',
      senderIdName: 'TXTLINK'
    })
  })
  
  if (!response.ok) {
    const error = await response.json()
    console.error('Error:', error.error)
    console.error('Error Code:', error.errorCode)
    // Handle specific error codes
    if (error.errorCode === 'INSUFFICIENT_CREDITS') {
      // Prompt user to top up
    }
  }
} catch (error) {
  console.error('Network error:', error)
}

Error Codes

Unauthorized

UNAUTHORIZED401

Invalid API key or credentials

Solution: Check that your API key is correct and active, or verify your username/password

Invalid Phone Number

INVALID_PHONE_NUMBER400

The phone number format is incorrect

Solution: Use E.164 format with country code (e.g., +254712345678)

Insufficient Credits

INSUFFICIENT_CREDITS402

Your account does not have enough credits

Solution: Top up your account from the dashboard

Sender ID Not Found

SENDER_ID_NOT_FOUND403

The specified sender ID does not exist or is not authorized

Solution: Check that the sender ID name is correct and approved for your account

Sender ID Inactive

SENDER_ID_INACTIVE400

The sender ID is not active

Solution: Wait for sender ID approval or contact support

Message Too Long

MESSAGE_TOO_LONG400

The message exceeds the maximum length

Solution: Split long messages into multiple parts or reduce message length

Rate Limit Exceeded

RATE_LIMIT_EXCEEDED429

Too many requests in a short period

Solution: Wait before making more requests or upgrade your plan

Internal Server Error

INTERNAL_SERVER_ERROR500

An unexpected error occurred on our servers

Solution: Retry the request. If the problem persists, contact support

HTTP Status Codes

Status Code	Meaning	Description
200	OK	Request succeeded
400	Bad Request	Invalid parameters or request format
401	Unauthorized	Invalid or missing authentication
402	Payment Required	Insufficient credits
403	Forbidden	Sender ID not authorized or access denied
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Error Handling Best Practices

Always check HTTP status codes before processing responses
Use error codes for programmatic error handling
Display user-friendly error messages to end users
Log error details for debugging
Implement retry logic for transient errors (5xx)
Handle rate limiting gracefully with exponential backoff