Errors & Troubleshooting

Reference for API error codes and common issues.

HTTP Status Codes

Code	Status	Description
200	OK	Request succeeded (GET)
201	Created	Resource created (POST)
202	Accepted	Request accepted for processing
204	No Content	Request succeeded, no response body (DELETE)
400	Bad Request	Invalid request data
401	Unauthorized	Missing or invalid API key
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Error Response Format

All errors return a JSON response:

{
  "error": "Error Type",
  "message": "Detailed error description",
  "validationErrors": {
    "fieldName": "Field-specific error message"
  }
}

Common Errors

401 Unauthorized

Missing API Key

{
  "error": "Unauthorized",
  "message": "Missing or invalid X-API-Key header. Please provide a valid API key."
}

Solution: Include the X-API-Key header in your request.

---

Invalid API Key

{
  "error": "Unauthorized",
  "message": "Invalid or revoked API key. Please check your credentials."
}

Solution: Verify your API key is correct and has not been revoked.

---

Invalid or Missing API Key

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key. Please check your credentials."
}

Solution: Ensure your API key is valid and included in the X-API-Key header. If the issue persists, generate a new key from the dashboard or contact support.

---

404 Not Found

Template Not Found

{
  "error": "Not Found",
  "message": "Template not found or access denied"
}

Solution: Check the templateId exists and belongs to your company.

---

Resource Not Found

{
  "error": "Not Found",
  "message": "Campaign not found"
}

Solution: Verify the resource ID is correct.

---

400 Bad Request

Invalid Phone Number

{
  "error": "Bad Request",
  "message": "Invalid phone number format",
  "validationErrors": {
    "phoneNumber": "Phone number must be 10-15 digits"
  }
}

Solution: Ensure phone numbers are 10-15 digits, optionally starting with +.

---

Too Many Recipients

{
  "error": "Bad Request",
  "message": "Maximum 200000 recipients allowed per request"
}

Solution: Split your recipients into smaller batches.

---

Media URL Not Accessible

{
  "error": "Bad Request",
  "message": "Image URL is not accessible",
  "validationErrors": {
    "imageUrl": "URL must be HTTPS and publicly accessible"
  }
}

Solution: Ensure media URLs are:

• Using HTTPS
• Publicly accessible (no authentication required)
• Returning a valid response

---

Campaign Not InProgress

{
  "error": "Campaign is not active",
  "message": "Campaign status is Draft. Messages can only be added to InProgress campaigns."
}

Solution: Only add messages to campaigns with InProgress status.

---

Cannot Add Messages to Bulk Campaign

{
  "error": "Bad Request",
  "message": "Cannot add messages to bulk campaign"
}

Solution: Messages can only be added individually to transactional campaigns. For bulk campaigns, use the bulk send endpoints.

---

Campaign Channel Type Mismatch

{
  "error": "Bad Request",
  "message": "Campaign is not an SMS campaign"
}

Solution: Ensure you are using the correct endpoint for the campaign's channel type.

---

Template Validation Errors

{
  "error": "Bad Request",
  "message": "Template validation failed",
  "validationErrors": {
    "templateContent": "Template content is required",
    "name": "Template name must be unique"
  }
}

Solution: Review the validationErrors dictionary for field-specific issues and correct them.

---

429 Too Many Requests

Rate Limit Exceeded (Pending Message Capacity)

{
  "error": "Rate limit exceeded",
  "message": "Too many pending messages. You have 48500 pending messages and requested 5000 more. Maximum allowed: 50000. Available capacity: 1500.",
  "currentPending": 48500,
  "requestedCount": 5000,
  "maxAllowed": 50000,
  "availableCapacity": 1500,
  "retryAfterSeconds": 30
}

Solution:

• Wait for the retryAfterSeconds period
• Implement exponential backoff
• Batch requests when possible

---

Troubleshooting Guide

Messages Not Delivering

1. Check message status

   GET /api/v1/messages?phoneNumber=38970123456

2. Review status codes:

   • Pending - Still in queue
   • Sending - Being processed
   • Failed - Check details field for reason

3. Common failure reasons:

   • Invalid phone number
   • Recipient not on Viber (for Viber messages)
   • Network issues

4. Viber-specific error codes:

   Code	Error	Description	SMS Fallback?
   8	USER_BLOCKED	User blocked the Viber service	Yes
   9	NOT_VIBER_USER	Recipient not registered on Viber	Yes
   10	NO_SUITABLE_DEVICE	No compatible device for Viber	Yes

   SMS Fallback

   If your template has SMS fallback enabled (smsFallbackEnabled: true), messages that fail with codes 8, 9, or 10 will automatically be sent via SMS. Check your campaign's smsFallbackDeliveredCount to see how many were successfully delivered via fallback.

Templates Not Creating

1. Validate message type - Must be 1-8 for Viber
2. Check Viber Service ID - Get from /api/v1/viber-services
3. Verify media URLs - Must be HTTPS and accessible
4. Check character limits:
   • Survey question: max 85 characters
   • Carousel title: 2-38 characters
   • Carousel items: 2-5 items
   • Survey options: 2-5 options

Rate Limit Issues

1. Batch recipients - Send many recipients per request
2. Use transactional campaigns - For real-time messages
3. Implement queuing - In your application
4. Add retry logic:

async function sendWithRetry(request, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, request);

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      await sleep(retryAfter * 1000);
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

Survey Responses Not Recording

1. Verify template type - Must be message type 6 (Survey)
2. Check campaign exists - Survey responses are tied to campaigns
3. Confirm delivery - Survey must be delivered before response is possible

Authentication Issues

1. Verify header name - Must be X-API-Key (HTTP headers are case-insensitive, but use this casing by convention)
2. Check for whitespace - No leading/trailing spaces in key
3. Confirm key is active - Check dashboard for key status
4. Use correct environment - Development vs production keys

Getting Help

If you continue to experience issues:

1. Check the status page for service outages
2. Review request/response logs for details
3. Contact your account manager with:
   • Request ID (if available)
   • Timestamp
   • Request body (sanitized)
   • Error response