Legacy API Notice: This documentation covers the Legacy Sent API (v2). For new integrations, please refer to the latest Sent API v3 Error Catalog.

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, templateVariables 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