Errors & Limits

HTTP Status Codes

| Status | Meaning | |--------|---------| | 200 OK | Request succeeded | | 201 Created | Resource created (templates, broadcasts) | | 400 Bad Request | Invalid request body or parameters | | 401 Unauthorized | Missing or invalid API key | | 403 Forbidden | Insufficient permissions | | 404 Not Found | Resource doesn’t exist | | 409 Conflict | Duplicate resource (e.g., template name) | | 429 Too Many Requests | Rate limit exceeded | | 500 Internal Server Error | Server error — retry with backoff |

Error Response Format

All errors return a consistent JSON structure:

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "The recipient phone number is not registered on WhatsApp.",
    "details": {
      "field": "to",
      "value": "1234567890"
    },
    "request_id": "req_abc123"
  }
}

Error Codes Reference

Message Errors

| Code | HTTP | Description | Solution | |------|------|-------------|----------| | INVALID_RECIPIENT | 400 | Number not on WhatsApp | Verify the number is registered | | INVALID_MESSAGE_TYPE | 400 | Unsupported message type | Check supported types in docs | | MESSAGE_TOO_LONG | 400 | Text exceeds 4,096 chars | Shorten the message | | OUTSIDE_WINDOW | 400 | 24h session expired | Use a template message | | TEMPLATE_NOT_FOUND | 404 | Template doesn’t exist | Check name and language code | | TEMPLATE_PAUSED | 400 | Template is paused by Meta | Fix quality issues, resubmit | | MEDIA_TOO_LARGE | 400 | File exceeds size limit | Compress or resize the file | | MEDIA_FORMAT_UNSUPPORTED | 400 | Unsupported file format | Convert to a supported format | | RECIPIENT_BLOCKED | 400 | User blocked your number | Remove from contact list |

Authentication Errors

| Code | HTTP | Description | Solution | |------|------|-------------|----------| | INVALID_API_KEY | 401 | API key is invalid or revoked | Check/regenerate your API key | | EXPIRED_API_KEY | 401 | API key has expired | Generate a new key | | INSUFFICIENT_PERMISSIONS | 403 | Key lacks required scope | Use a key with correct permissions | | IP_NOT_ALLOWED | 403 | Request from blocked IP | Add IP to allowlist |

Rate Limit Errors

| Code | HTTP | Description | Solution | |------|------|-------------|----------| | RATE_LIMITED | 429 | Too many requests/second | Wait and retry with backoff | | DAILY_LIMIT_REACHED | 429 | Daily message quota exceeded | Upgrade plan or wait until reset | | BROADCAST_LIMIT | 429 | Max broadcasts/day reached | Wait or upgrade plan |

Account Errors

| Code | HTTP | Description | Solution | |------|------|-------------|----------| | ACCOUNT_SUSPENDED | 403 | Account is suspended | Contact support | | WABA_DISCONNECTED | 403 | WhatsApp Business Account disconnected | Reconnect in dashboard | | NUMBER_NOT_VERIFIED | 403 | Phone number not verified | Complete verification flow |

Rate Limits

API Rate Limits (per API key)

| Plan | Requests/sec | Daily Messages | |------|-------------|----------------| | Free | 10 | 1,000 | | Premium | 100 | 100,000 | | Enterprise | Up to 1,000 | Unlimited |

WhatsApp Throughput (set by Meta)

Message throughput is controlled by Meta based on your phone number’s quality rating:

| Tier | Unique Users/24h | How to Reach | |------|-------------------|--------------| | Tier 1 | 1,000 | New numbers start here | | Tier 2 | 10,000 | Maintain quality + volume | | Tier 3 | 100,000 | Consistent quality + higher volume | | Tier 4 | Unlimited | Highest quality + highest volume |

StartMessaging handles all Meta-level throttling automatically — you don’t need to manage it yourself.

Implementing Retry Logic

async function sendWithRetry(payload, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://api.startmessaging.com/v1/messages', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(payload),
      });

      if (response.status === 429) {
        const retryAfter = response.headers.get('Retry-After') || Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (response.status >= 500) {
        await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
        continue;
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
      await new Promise(resolve => setTimeout(resolve, Math.pow(2, attempt) * 1000));
    }
  }
}

FAQ

What should I do if I keep getting OUTSIDE_WINDOW errors? The 24-hour customer service window has expired. You must use an approved template message to re-initiate the conversation.

How do I check my current rate limit usage? Check the X-RateLimit-Remaining and X-RateLimit-Reset response headers on any API call.

My quality rating dropped — what can I do? Reduce marketing messages, improve opt-in practices, and make it easy for users to opt out. Quality ratings recover automatically when complaint rates decrease.