Error Handling

The GB Chat API uses standard HTTP response codes and returns detailed error information in JSON format.

Response Format

Successful Response

{
  "success": true,
  "data": {
    "messageId": "msg_abc123xyz",
    "status": "sent"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Phone number is required",
    "details": {
      "field": "to",
      "issue": "required"
    }
  }
}

HTTP Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - IP not allowed or API disabled
404	Not Found - Template not found
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Codes

Authentication Errors

Code	HTTP Status	Description
INVALID_API_KEY	401	API key is missing or invalid
API_DISABLED	403	API access is disabled for this account
IP_NOT_ALLOWED	403	Request IP not in whitelist

Validation Errors

Code	HTTP Status	Description
VALIDATION_ERROR	400	Request body validation failed
INVALID_PHONE	400	Phone number format is invalid
INVALID_TEMPLATE	400	Template name is invalid

Resource Errors

Code	HTTP Status	Description
TEMPLATE_NOT_FOUND	404	Template doesn't exist or isn't approved
ACCOUNT_NOT_FOUND	404	WhatsApp account not found
NO_ACTIVE_ACCOUNT	400	No active WhatsApp account available

Rate Limiting

Code	HTTP Status	Description
RATE_LIMIT_EXCEEDED	429	Too many requests

Server Errors

Code	HTTP Status	Description
INTERNAL_ERROR	500	Something went wrong on our end
WHATSAPP_ERROR	500	WhatsApp API returned an error

Handling Errors

JavaScript/Node.js

async function sendMessage(payload) {
  try {
    const response = await fetch('https://inboxapi.workmatic.in/api/v1/message/send', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.GBCHAT_API_KEY,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(payload),
    });

    const data = await response.json();

    if (!data.success) {
      switch (data.error.code) {
        case 'RATE_LIMIT_EXCEEDED':
          // Wait and retry
          await sleep(parseInt(response.headers.get('Retry-After')) * 1000);
          return sendMessage(payload);

        case 'TEMPLATE_NOT_FOUND':
          console.error('Template not approved:', payload.template);
          break;

        case 'VALIDATION_ERROR':
          console.error('Invalid request:', data.error.message);
          break;

        default:
          console.error('API Error:', data.error);
      }
      throw new Error(data.error.message);
    }

    return data.data;
  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

Python

import requests
import time
import os

def send_message(payload):
    try:
        response = requests.post(
            'https://inboxapi.workmatic.in/api/v1/message/send',
            headers={
                'X-API-Key': os.environ['GBCHAT_API_KEY'],
                'Content-Type': 'application/json',
            },
            json=payload
        )

        data = response.json()

        if not data['success']:
            error = data['error']

            if error['code'] == 'RATE_LIMIT_EXCEEDED':
                retry_after = int(response.headers.get('Retry-After', 60))
                time.sleep(retry_after)
                return send_message(payload)

            raise Exception(f"{error['code']}: {error['message']}")

        return data['data']

    except requests.RequestException as e:
        print(f"Request failed: {e}")
        raise

Best Practices

Log Errors with Context

Always log the full error response for debugging:

if (!data.success) {
  console.error('API Error', {
    code: data.error.code,
    message: data.error.message,
    details: data.error.details,
    request: { to: payload.to, template: payload.template },
    timestamp: new Date().toISOString(),
  });
}

Handle Transient Errors

Some errors are temporary and can be retried:

• 429 RATE_LIMIT_EXCEEDED - Wait and retry
• 500 INTERNAL_ERROR - Retry with exponential backoff

Don't Retry Permanent Errors

Some errors won't succeed on retry:

• 401 INVALID_API_KEY - Fix your API key
• 404 TEMPLATE_NOT_FOUND - Check template name/status
• 400 VALIDATION_ERROR - Fix the request

Notify on Critical Errors

Set up alerts for errors that need attention:

if (error.code === 'API_DISABLED' || error.code === 'INVALID_API_KEY') {
  await sendSlackAlert('GB Chat API authentication failed!');
}