Skip to main content
Diagnose and fix common API errors. This section explains authentication failures, forbidden access, and why requests might return no matches.

​
Error Codes Reference

Every ChatAds error response includes a code field. Here’s the complete list:
CodeHTTP StatusDescriptionResolution
UNAUTHORIZED401No API key providedAdd x-api-key header
MISSING_API_KEY401API key header missingAdd x-api-key header
INVALID_API_KEY403Invalid API keyCheck key in Settings → API Keys
API_KEY_DISABLED403API key disabledRe-enable in dashboard or create new key
INVALID_INPUT400Empty or malformed requestCheck request body format
MESSAGE_TOO_LONG400Message exceeds 5000 charactersTrim message content
BLOCKED_KEYWORD400Blocked keyword detectedReview blocked keywords in Settings
COUNTRY_NOT_ALLOWED400Country not allowedUpdate geo restrictions
IP_COUNTRY_NOT_ALLOWED400IP geo-location blockedCheck IP-based geo restrictions
LANGUAGE_NOT_ALLOWED400Language not allowedUpdate language restrictions
DAILY_LIMIT_EXCEEDED429Daily limit reachedWait for reset at midnight UTC
MONTHLY_LIMIT_EXCEEDED429Monthly limit reachedUpgrade plan
INTERNAL_ERROR500Server errorRetry or contact support
REDIS_UNAVAILABLE503Rate limiter temporarily downRetry in a few seconds
Error responses don’t count against your quota (except DAILY_LIMIT_EXCEEDED and MONTHLY_LIMIT_EXCEEDED).

​
Common Questions

This means no API key was provided. Check that you’re including the x-api-key header:
curl -X POST 'https://api.getchatads.com/v1/chatads/messages' \
  -H 'x-api-key: cak_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{"message": "test"}'
Common issues:
  • Header name should be x-api-key
  • Don’t include “Bearer” prefix—just the key itself
This means your API key is invalid or disabled. Verify:
  1. The key starts with cak_
  2. It hasn’t been revoked in the dashboard
  3. Your team account is active
Generate a new key at getchatads.com/settings/api-keys.
Several reasons can cause no match (check data.returned === 0 or empty data.offers array):
  1. No product detected - The message doesn’t contain a clear product reference
  2. Intent too low - The query’s intent score didn’t meet the threshold
  3. No affiliate available - The product exists but has no affiliate link
  4. Message too short - After removing PII and blocked keywords, no words remain
  5. Non-US/non-English - Traffic from outside the US or in a non-English language
Note: Blocked keywords return BLOCKED_KEYWORD (400) instead of an empty response.Technical note: After sanitization (removing PII, URLs, blocked keywords), messages may become too short for product extraction even if they started longer. Single-word product names are supported.Check the data.status field to understand the outcome. When status is "no_offers_found", examine the response to determine why no offers were returned.
ChatAds requires at least 1 word after sanitization to extract product keywords. Sanitization removes:
  • PII (emails, phone numbers, SSNs, credit card numbers)
  • URLs and links
  • Blocked keywords from your rules
A message like “Buy this: user@email.com” becomes just “Buy this:” after sanitization—too short to process. Send messages with clear product context to avoid this error.