Skip to main content

Troubleshooting

This page is the practical troubleshooting path for public API integrations.

Use it when an integration is not working and you need to isolate the failure quickly.

The fastest debugging order​

Debug in this order:

  1. token acquisition
  2. /api/core/whoami
  3. /api/core/numbers
  4. POST /api/core/messages/send
  5. webhook receipt and signature verification

Do not start by debugging delivery lifecycle if authentication and number ownership are not already confirmed.

Symptom: token request fails​

Check:

  • client_id
  • client_secret
  • grant_type=client_credentials
  • form-encoded request shape

Likely causes:

  • invalid credentials
  • inactive API client
  • inactive parent account
  • malformed token request

Best next action:

  • correct credentials or account status before testing CORE routes

Symptom: /api/core/whoami fails​

Check:

  • bearer token format
  • whether the token was freshly acquired
  • whether the token is expired

Likely causes:

  • missing or malformed Authorization header
  • expired token
  • invalid token
  • inactive client context

Best next action:

  • acquire a fresh token and retry once

Symptom: /api/core/numbers succeeds but sends fail​

Check:

  • sendFrom uses numberId, not the phone number
  • the selected number is ACTIVE
  • smsEnabled or mmsEnabled matches the message type

Likely causes:

  • using E.164 in sendFrom
  • using a number not owned by the API client
  • sending with a number not enabled for the intended message type

Best next action:

  • correct the sendFrom source and re-run the send

Symptom: send request returns 400 INVALID_REQUEST​

Check:

  • Idempotency-Key is present
  • to[] contains valid E.164 values
  • text and media rules match the message type
  • the body shape matches the reference

Likely causes:

  • missing Idempotency-Key
  • invalid recipient format
  • invalid request shape
  • SMS request including media
  • MMS request missing media

Best next action:

  • correct the payload; do not blindly retry unchanged invalid requests

Symptom: send request returns 403 FORBIDDEN​

Check:

  • sendFrom belongs to the authenticated API client
  • the token belongs to the client you think it does

Likely causes:

  • wrong API client context
  • wrong sendFrom
  • number ownership mismatch

Best next action:

  • confirm /whoami, then confirm /numbers, then retry with the correct numberId

Symptom: send request returns 202 but no delivery happens​

Remember:

  • 202 with QUEUED means accepted into Red Cloud
  • it does not guarantee final delivery

Check:

  • webhook endpoint is reachable
  • webhook signatures are being verified correctly
  • downstream webhook handling is not discarding the event
  • you are inspecting message.sent, message.delivery, and message.failed

Likely causes:

  • webhook endpoint misconfiguration
  • webhook processing bug
  • provider-side downstream failure reported later by webhook

Best next action:

  • inspect webhook receipts before assuming the send path is broken

Symptom: no webhook events arrive​

Check:

  • endpoint URL is correct
  • endpoint is publicly reachable
  • your handler returns 2xx only after successful acceptance
  • signature handling is not rejecting valid traffic
  • inbound and delivery webhook configuration is actually enabled for the client or number path being tested

Likely causes:

  • unreachable endpoint
  • invalid signature verification logic
  • endpoint returns non-2xx
  • webhook configuration issue

Best next action:

  • test with a temporary endpoint such as webhook.site, then compare behavior

Symptom: duplicate messages appear​

Check:

  • whether the same business operation was sent under different idempotency keys
  • whether a timeout caused a retry with a new key
  • whether the client retried after ambiguous outcome without reusing the same key

Likely causes:

  • incorrect idempotency strategy
  • retrying as a new operation instead of the same operation

Best next action:

What to capture before escalation​

Before escalating a problem, collect:

  • endpoint called
  • HTTP status
  • request timestamp
  • requestId from the CORE error wrapper, if present
  • request payload shape, excluding secrets
  • whether the token was freshly acquired
  • whether the issue reproduces consistently
  • messageId if the request was accepted

That is the minimum useful package for support or engineering escalation.