Error Catalog

Comprehensive catalog of all errors you may encounter when using the Sent API, including their causes and remediation steps.

Authentication Errors (401)

AUTH-001: Missing API Key

Error: "Header x-api-key not found" Cause: The required x-api-key header was not provided in the request. Remediation: Include the x-api-key header with your API key value.

curl -H "x-api-key: your-api-key-here" \
  https://api.sent.dm/v1/contacts

AUTH-002: Missing Sender ID

Error: "Header x-sender-id not found" Cause: Customer API endpoints require both x-api-key and x-sender-id headers. Remediation: Include both headers in customer API requests.

curl -H "x-api-key: your-api-key-here" \
     -H "x-sender-id: your-customer-id" \
  https://api.sent.dm/v1/contacts

AUTH-003: Invalid API Credentials

Error: "Invalid API credentials!" Cause: The provided API key is invalid, expired, or disabled. Remediation:

Verify your API key is correct
Check if the API key is active in your account
Generate a new API key if needed

AUTH-004: Invalid Customer Claims

Error: "Invalid customer claims" Cause: The customer ID in the token doesn't match the sender ID header. Remediation: Ensure the x-sender-id matches your authenticated customer account.

Validation Errors (400)

VAL-001: Required Field Missing

Error: "Field is required" Common Fields:

phoneNumber: Phone number is required
templateId: Template ID is required
customerId: Customer ID is required
contactId: Contact ID is required

Remediation: Include all required fields in your request body.

VAL-002: Invalid UUID Format

Error: "Invalid UUID format" Fields: customerId, contactId, templateId, id Cause: The provided ID is not a valid UUID format. Remediation: Use valid UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000).

VAL-003: Empty or Whitespace Value

Error: "Field cannot be empty" Common Fields: name, phoneNumber, messageBody Remediation: Provide non-empty values for required string fields.

VAL-004: Invalid Pagination Parameters

Errors:

"Page must be zero or greater"
"PageSize must be greater than zero"

Remediation: Use valid pagination values:

{
  "page": 0,    // >= 0
  "pageSize": 20 // > 0
}

VAL-005: Phone Number Array Validation

Errors:

"At least one phone number is required"
"Maximum 10 phone numbers allowed"
"Duplicate phone numbers not allowed"
"Empty phone numbers not allowed"

Remediation:

Provide 1-10 unique, non-empty phone numbers
Remove duplicates from the array
Use international format (+1234567890)

Business Logic Errors (400)

BUS-001: Invalid Phone Number

Error: "Invalid phone number" Cause: Phone number format is unrecognizable or invalid. Remediation:

Use E.164 international format: +1234567890
Include country code
Remove special characters except +
Validate locally before sending

BUS-002: Invalid Contact ID

Error: "Invalid contact id" Cause: The contact ID format is invalid or malformed. Remediation: Use valid UUID format for contact IDs.

BUS-003: Template Not Found

Error: "Template not found" Cause: The specified template doesn't exist or isn't accessible to your customer account. Remediation:

Verify template ID is correct
Ensure template is published (published: true)
Check template belongs to your customer account
For WhatsApp templates, verify approval status

BUS-004: Insufficient Balance

Error: "Insufficient balance. Current balance: 0.0050, estimated cost: 0.0200" Cause: Account balance is insufficient to send the message. Remediation:

Add funds to your account
Monitor balance levels proactively
Implement balance alerts
Check estimated costs before sending

BUS-005: Invalid Channel

Error: "Invalid channel: email. Supported channels are: sms, whatsapp" Cause: Specified channel type is not supported. Remediation: Use supported channel types: sms or whatsapp.

BUS-006: Channel Provider Not Found

Error: "Channel provider not found for type: {channelType}" Cause: Internal configuration issue with channel providers. Remediation: Contact support if this error persists.

BUS-007: Failed to Register New Contact

Error: "Failed to register new contact" Cause: Database or validation error during contact creation. Remediation:

Verify phone number is valid
Check for existing contact with same number
Retry the operation
Contact support if error persists

BUS-008: Failed Channel Operations

Errors:

"Failed to retrieve contact after channel update"
"Failed to retrieve contact after channel refresh"

Cause: Database consistency issue during channel operations. Remediation: Retry the operation after a brief delay.

Not Found Errors (404)

NOT-001: Contact Not Found

Error: "Contact not found" Cause: The specified contact doesn't exist for your customer account. Remediation:

Verify contact ID is correct
Check if contact belongs to your customer account
For phone lookups, the contact may need to be created first

NOT-002: Customer Not Found

Error: "Customer not found" Cause: The customer ID is invalid or doesn't exist. Remediation: Verify the customer ID is correct and active.

NOT-003: Resource Not Found

Error: Generic 404 error Cause: The requested endpoint or resource doesn't exist. Remediation:

Check the API endpoint URL
Verify HTTP method (GET, POST, etc.)
Ensure proper API versioning

NOT-004: Endpoint Not Implemented

Error: "Not Implemented" Cause: The endpoint exists but functionality is not yet implemented. Example: POST /contacts/csv Remediation: Use alternative endpoints or wait for implementation.

External Service Errors (400/500)

EXT-001: WhatsApp API Errors

Cause: WhatsApp Business API returned an error. Common Issues:

Template not approved
Rate limits exceeded
Invalid WhatsApp Business Account
Phone number not registered with WhatsApp Business

Remediation:

Check WhatsApp template status
Verify WhatsApp Business Account configuration
Monitor rate limits
Contact WhatsApp support for account issues

EXT-002: SMS Provider (Telnyx) Errors

Cause: Telnyx SMS API returned an error. Common Issues:

Invalid messaging profile
Phone number not authorized for SMS
Rate limits or compliance restrictions

Remediation:

Verify Telnyx configuration
Check phone number capabilities
Review messaging profile settings
Contact Telnyx support

EXT-003: Phone Number Validation Errors

Cause: RapidAPI phone validation service issues. Remediation:

Check RapidAPI key configuration
Verify service availability
Implement fallback validation

Internal Server Errors (500)

SRV-001: Database Connection Failed

Cause: Database connection or query execution failure. Remediation:

Retry the operation
Contact support if error persists
Check service status page

Retry the operation
Contact support with request details
Check for service announcements

Webhook Errors

WEB-001: Webhook Timeout

Cause: Your webhook endpoint took longer than 5 seconds to respond. Remediation:

Optimize webhook handler performance
Implement asynchronous processing
Return 2xx status quickly, process later

WEB-002: Webhook Not Reachable

Cause: Webhook URL is not accessible or returns non-2xx status. Remediation:

Verify webhook URL is correct and publicly accessible
Implement proper error handling in webhook
Return appropriate HTTP status codes

WEB-003: Webhook Processing Failed

Cause: Error processing incoming webhook data. Remediation:

Validate webhook payload structure
Implement proper JSON parsing
Log webhook data for debugging

Error Handling Strategies

1. Implement Proper Retry Logic

async function sendMessageWithRetry(payload, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await sendMessage(payload);
    } catch (error) {
      if (error.status < 500 || attempt === maxRetries) {
        throw error; // Don't retry client errors or final attempt
      }
      
      const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

2. Monitor and Alert on Errors

Set up alerts for 4xx error spikes
Monitor balance levels
Track template approval status
Alert on webhook failures

3. Graceful Error Recovery

try {
  await sendMessage(payload);
} catch (error) {
  if (error.detail?.includes('Insufficient balance')) {
    // Trigger balance top-up flow
    await handleInsufficientBalance();
  } else if (error.detail?.includes('Template not found')) {
    // Fall back to default template
    payload.templateId = fallbackTemplateId;
    return sendMessage(payload);
  }
  throw error;
}

4. Logging and Debugging

Log full error responses for debugging
Include correlation IDs in logs
Monitor error patterns and trends
Implement structured logging

For additional support, contact our technical team with:

Error details and status code
Request payload (without sensitive data)
Timestamp and correlation ID
Steps to reproduce the issue

On this page