Common Issues

Solutions to frequently encountered problems, organised by area. Each entry shows the symptom (including the actual error message where the API returns one), the likely cause, and the fix.

Authentication

401: Authorization header missing or invalid

Symptom:

{"error": "Authorization header missing or invalid. Include 'Authorization: Bearer YOUR_TOKEN' header."}

Cause: The request has no Authorization header, or it isn’t in Bearer format.

Fix: Send your API key as a bearer token:

curl https://api.outeract.com/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ events(limit: 1) { id } }"}'

401: Invalid API key

Symptom: {"error": "Invalid API key"}

Cause: The key doesn’t exist. It was mistyped, truncated, deleted, or rotated.

Fix: Copy the key again from the console (Settings → API Keys). Keys are shown once at creation; if you’ve lost the value, create a new key. If you recently rotated the key, make sure every deployment picked up the new value.

401: API key is disabled / API key has expired

Symptom: {"error": "API key is disabled"} or {"error": "API key has expired"}

Cause: The key was toggled off in the console, or its expiresAt date has passed.

Fix: Re-enable the key or create a replacement. Check the key’s status in the console under Settings → API Keys.

API key validation is cached briefly on the server, so a just-revoked key may keep working for a short time, and a just-created key is picked up immediately.

Resource belongs to a different application

Symptom: Queries return empty results, or Platform connection not found for current organisation style errors, even though the resource exists.

Cause: Each API key is scoped to exactly one application. Querying with a key from a different application won’t find the resource.

Fix: Use a key belonging to the application that owns the resource. The console shows which application each key belongs to under Settings → API Keys.

Sending Messages

Recipient user not found or not in current application

Symptom: sendMessage fails with Recipient user not found or not in current application.

Cause: The userId you passed belongs to a different application, or doesn’t exist.

Fix: Users are per-application. Query users in the same application (same API key) to confirm the ID.

Recipient user does not have a platform account

Symptom: Recipient user does not have a whatsapp account (or another platform name).

Cause: You asked Outeract to send on a platform where the recipient has no identity. A user only gains a platform identity when they message you on that platform or when you create the identity explicitly.

Fix: Check the user’s identities:

query {
  user(id: "USER_ID") {
    id
    identities { id identityType externalId }
  }
}

Either send on a platform the user actually has, or omit the platform and let Outeract infer it from the recipient’s identities on enabled connections.

Platform connection is disabled

Symptom: Platform connection <name> is disabled and cannot send messages

Cause: The connection’s enabled toggle is off. Disabled connections are also skipped during platform inference, which can surface as “no account” errors instead.

Fix: Re-enable the connection in the console (Integrations) or via updatePlatformConnection.

No connection found for this application

Symptom: No whatsapp connection found for this application or No platform connections found for this application

Cause: The application has no connection for the requested platform (or none at all).

Fix: Create the platform connection first; see the platform guides. If you passed an explicit platformConnectionId, verify it with Platform connection not found or not in current application in mind: connections are per-application too.

Validation errors

Symptom: Errors like Invalid user_id: <value>. Must be a valid UUID. or Identity <id> does not exist.

Cause: A malformed or stale ID in the mutation arguments.

Fix: All entity IDs are UUIDs. Re-query the entity to get the current ID rather than caching IDs across environments.

Message accepted but never delivered

Symptom: sendMessage succeeds but the recipient never receives anything; the message event shows delivery_status.failed_at set.

Cause: Platform-side rejection, most commonly the 24-hour messaging window on WhatsApp/Instagram/Facebook (error_type: messaging_window_closed).

Fix: See OUTSIDE_MESSAGING_WINDOW and use a pre-approved template. Subscribe to system.message_delivery_failed webhooks to be notified of asynchronous failures.

Webhooks Not Arriving

Event pattern doesn’t match

Symptom: Deliveries never appear for certain event types, while others arrive fine.

Cause: Webhook subscriptions match eventTypes patterns against the event’s type using shell-style wildcards (fnmatch). message.* matches message.inbound and message.outbound; a bare message matches nothing. Events without an event type never match any pattern.

Fix: Open the subscription in the console (Settings → Webhooks) and check its patterns: widen them (message.*, or * for everything) or add the missing exact type. Also confirm the subscription is enabled; disabled subscriptions receive nothing.

Endpoint returns 4xx/5xx

Symptom: Deliveries show failed status with your endpoint’s status code.

Cause: Your endpoint rejected the request. Outeract retries failed deliveries up to the subscription’s max attempts (default 5) on an exponential schedule (5 s, 5 m, 30 m, 2 h, 5 h after each failed attempt), then marks the delivery failed permanently.

Fix: Inspect the delivery records on the subscription’s detail page in the console. They include the response code, error message and attempt count for every attempt.

Return a 2xx quickly (do heavy processing asynchronously), and make sure the URL is publicly reachable over HTTPS with a valid certificate.

Subscription was automatically disabled

Symptom: Deliveries stop entirely; the subscription shows as disabled in the console with a reason given, and its health status reads disabled.

Cause: Outeract auto-disables a subscription after 20 consecutive delivery failures with no successful delivery in the last 24 hours, typically an endpoint that has been down or rejecting requests for a sustained period. A system.webhook_endpoint_disabled event is emitted when this happens (subscribe to system.* on another endpoint to be notified).

Fix: Repair the endpoint, then re-enable the subscription in the console; the webhook detail page shows a re-enable banner. Re-enabling resets the failure counters.

Signature verification fails

Symptom: Your endpoint rejects every delivery as having a bad signature.

Cause: Common verification bugs: signing the parsed/re-serialised JSON instead of the raw request body, dropping the sha256= prefix, or comparing against a base64 digest.

Fix: Outeract sends an HMAC-SHA256 of the raw request body, keyed with the subscription’s secret, in the X-Outeract-Signature header formatted as sha256=<hex digest>:

import hmac, hashlib

def verify(secret: str, raw_body: bytes, header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, header)

Use the subscription’s test action in the console to send a signed test delivery on demand; see Debugging.

Platform Connections

OAuth token expired or revoked

Symptom: Sends fail with platform errors like INVALID_TOKEN; the connection health check reports authentication failures.

Cause: The platform-side access token expired, or the user revoked access / changed their password on the platform.

Fix: Open the connection in the console and run a health check to confirm, then reconnect via OAuth from the same page.

Health check failures

Symptom: A health check reports the connection as invalid, with one or more failing tests.

Cause: Each test pinpoints a different problem: credential validation, webhook registration, API quota. A failing webhook test usually means the platform-side webhook subscription was removed or points at a stale URL.

Fix: Fix the failing test’s area. For webhook registration issues, the connection’s Reconnect Webhook action in the console re-registers the webhook with the platform (for platforms that support auto-setup).

Invalid configuration on create/update

Symptom: Invalid configuration: <field errors> when creating or updating a connection.

Cause: The connection’s config is validated against the platform’s config form schema: missing required fields (tokens, phone number IDs, etc.) or wrong types.

Fix: Query availablePlatforms to see each platform’s required config fields, or use the console’s connection form, which renders the same schema.

Rate Limiting

429: Rate limit exceeded