Error Codes

Complete reference of HueChat API error codes and how to handle them.

Error Response Format

All errors return a consistent JSON structure:

{
  "error": "error_code",
  "message": "Human-readable description",
  "code": 400,
  "details": {
    "field": "phone",
    "reason": "Invalid format"
  },
  "request_id": "req_abc123xyz",
  "timestamp": "2026-01-25T10:30:00Z"
}

Field	Description
error	Machine-readable error code
message	Human-readable description
code	HTTP status code
details	Additional context (optional)
request_id	Unique request ID for support
timestamp	When the error occurred

HTTP Status Codes

Code	Category	Description
400	Client Error	Bad request - invalid input
401	Client Error	Unauthorized - invalid API key
403	Client Error	Forbidden - insufficient permissions
404	Client Error	Not found - resource doesn't exist
409	Client Error	Conflict - duplicate resource
422	Client Error	Unprocessable - validation failed
429	Client Error	Rate limited - too many requests
500	Server Error	Internal error - contact support
502	Server Error	Bad gateway - temporary issue
503	Server Error	Service unavailable - maintenance

Authentication Errors

unauthorized

HTTP Status: 401

API key is missing, invalid, or revoked.

{
  "error": "unauthorized",
  "message": "Invalid API key",
  "code": 401
}

Solutions:

• Check your API key is correct
• Ensure the key hasn't been revoked
• Verify you're using the correct header (X-API-Key or Authorization: Bearer)

forbidden

HTTP Status: 403

API key doesn't have permission for this action.

{
  "error": "forbidden",
  "message": "API key does not have permission for contacts:write",
  "code": 403,
  "details": {
    "required_permission": "contacts:write",
    "key_permissions": ["contacts:read"]
  }
}

Solutions:

• Create a new API key with required permissions
• Contact your admin to update key permissions

Validation Errors

invalid_input

HTTP Status: 400

Request body contains invalid data.

{
  "error": "invalid_input",
  "message": "Request validation failed",
  "code": 400,
  "details": {
    "field": "phone",
    "reason": "Phone number must be in E.164 format",
    "received": "1234567890",
    "expected": "+1234567890"
  }
}

Common causes:

• Invalid phone number format (must be E.164: +1234567890)
• Invalid email format
• Missing required fields
• Invalid enum values

missing_field

HTTP Status: 400

Required field is missing from request.

{
  "error": "missing_field",
  "message": "Required field 'first_name' is missing",
  "code": 400,
  "details": {
    "field": "first_name"
  }
}

invalid_json

HTTP Status: 400

Request body is not valid JSON.

{
  "error": "invalid_json",
  "message": "Could not parse request body as JSON",
  "code": 400
}

Resource Errors

not_found

HTTP Status: 404

Requested resource doesn't exist.

{
  "error": "not_found",
  "message": "Contact not found",
  "code": 404,
  "details": {
    "resource_type": "contact",
    "identifier": "cnt_nonexistent123"
  }
}

Solutions:

• Verify the resource ID is correct
• Check if the resource was deleted
• Ensure you're using the correct environment (live vs sandbox)

duplicate_contact

HTTP Status: 409

Contact already exists with this identifier.

{
  "error": "duplicate_contact",
  "message": "A contact with this phone number already exists",
  "code": 409,
  "details": {
    "existing_contact_id": "cnt_abc123",
    "duplicate_field": "phone"
  }
}

Solutions:

• Use the existing contact ID
• Update the existing contact instead
• Use a different phone/email

Channel Errors

channel_not_connected

HTTP Status: 400

Trying to send message through a disconnected channel.

{
  "error": "channel_not_connected",
  "message": "WhatsApp channel is not connected",
  "code": 400,
  "details": {
    "channel": "whatsapp"
  }
}

window_expired

HTTP Status: 400

WhatsApp 24-hour messaging window has closed.

{
  "error": "window_expired",
  "message": "The 24-hour messaging window has expired. Use a template message.",
  "code": 400,
  "details": {
    "window_closed_at": "2026-01-24T10:30:00Z",
    "suggested_action": "Send template message"
  }
}

Solution: Use a template message to reinitiate conversation.

template_not_found

HTTP Status: 400

Message template doesn't exist or isn't approved.

{
  "error": "template_not_found",
  "message": "Template 'promo_offer' not found or not approved",
  "code": 400,
  "details": {
    "template_name": "promo_offer"
  }
}

invalid_template_parameters

HTTP Status: 400

Template parameters don't match the template definition.

{
  "error": "invalid_template_parameters",
  "message": "Template requires parameter 'order_id'",
  "code": 400,
  "details": {
    "template_name": "order_confirmation",
    "missing_parameters": ["order_id"],
    "provided_parameters": ["customer_name"]
  }
}

Rate Limit Errors

rate_limited

HTTP Status: 429

Too many requests in the time window.

{
  "error": "rate_limited",
  "message": "Rate limit exceeded. Retry after 60 seconds.",
  "code": 429,
  "details": {
    "limit": 100,
    "window": "1 minute",
    "retry_after": 60
  }
}

Headers included:

Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706215260

contact_rate_limited

HTTP Status: 429

Too many messages sent to a specific contact.

{
  "error": "contact_rate_limited",
  "message": "Message rate limit exceeded for this contact",
  "code": 429,
  "details": {
    "contact_id": "cnt_abc123",
    "limit": 100,
    "window": "1 minute"
  }
}

Webhook Errors

webhook_delivery_failed

Webhook couldn't be delivered after all retries.

{
  "error": "webhook_delivery_failed",
  "message": "Webhook delivery failed after 8 attempts",
  "code": 500,
  "details": {
    "webhook_id": "wh_abc123",
    "last_attempt": "2026-01-25T12:00:00Z",
    "last_error": "Connection timeout"
  }
}

invalid_webhook_url

HTTP Status: 400

Webhook URL is invalid or unreachable.

{
  "error": "invalid_webhook_url",
  "message": "Webhook URL must be HTTPS",
  "code": 400,
  "details": {
    "url": "http://example.com/webhook",
    "reason": "HTTPS required"
  }
}

Server Errors

internal_error

HTTP Status: 500

Unexpected server error.

{
  "error": "internal_error",
  "message": "An unexpected error occurred",
  "code": 500,
  "request_id": "req_abc123xyz"
}

Action: Contact support with the request_id.

service_unavailable

HTTP Status: 503

Service is temporarily unavailable.

{
  "error": "service_unavailable",
  "message": "Service temporarily unavailable. Please retry.",
  "code": 503,
  "details": {
    "retry_after": 30
  }
}

Error Handling Best Practices

Retry Logic

async function makeRequest(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 429) {
        // Rate limited - wait and retry
        const waitTime = error.details?.retry_after || 60;
        await sleep(waitTime * 1000);
        continue;
      }
      if (error.code >= 500) {
        // Server error - exponential backoff
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
      // Client error - don't retry
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

Logging Errors

Always log the request_id for support:

except HueChatError as e:
    logger.error(
        f"HueChat API error: {e.message}",
        extra={
            "error_code": e.error,
            "request_id": e.request_id,
            "details": e.details
        }
    )