Troubleshooting

Each entry starts from what you see, then gives the likely cause, how to confirm it and the fix. For what a single reason_code means, see Outcomes. To see what Drop Cowboy® received from you and what it sent to your webhook URL, start with Look up a request or delivery in your API logs.

Look up a request or delivery in your API logs

The API logs show every call you made with your API keys and every delivery to your webhook URLs, so you can see what actually arrived and what your server answered. In the dashboard, open Settings, then API Logs. It is also the Logs tab next to API Keys and Webhooks.

Find a request

  1. On the Requests tab, choose request_id or message_id next to Find by ID, paste the value and search.
  2. Click the row to open it.

Which id to search for depends on the route you called:

You called Search by Where the id is
A REST route such as contacts, lists or tags request_id meta.request_id in the response, and the X-Request-Id header
A send route: /rvm, /sms, /voice-broadcast or /ai-broadcast message_id The 202 body

To see everything one key did, open Settings, then API Keys, and click the key's request count or Logs. That opens the logs filtered to the key. You can also filter by source, HTTP status, send result and date.

An open row shows:

  • The result. For a REST call that is the HTTP status. For a send it is VALID or INVALID.
  • The validation message, when a send was refused. It names the check that failed, including a wrong secret, a revoked key or a missing scope on one of your keys.
  • The request body, so you can compare it with what your code meant to send.
  • The response body, when the call failed, or on success while Store successful response bodies is on (see What the logs keep). For a send it is the 202 body your client received, which is the same whether or not the send passed.
  • Each attempt to reach the send's callback_url: the URL, the status code your server answered, and any error. Webhook deliveries are on the Webhooks tab instead.

VALID means the send passed the checks made when the request arrived. The result of the send itself arrives later, as Send lifecycle describes.

Find a webhook delivery

Open the Webhooks tab, then click a delivery. The drawer shows:

  • Payload sent, the event we posted to your URL.
  • Response from your endpoint, the status code and body your server returned, with the attempt number, the duration and any error.

Filter by webhook, status, event type and date to narrow the list. Deliveries can't be resent from the log. See Delivery and retries for when we retry.

What the logs keep

  • Request bodies are kept for writes, for sends and for errors. Secrets, tokens and passwords are removed before anything is stored, and long bodies are cut short. A webhook payload is cut at 8 KB.
  • Response bodies are kept for errors (HTTP 400 and above), and for every send. To keep the JSON a REST route returns on success as well, turn on Store successful response bodies at the top of the Requests tab. It applies to requests made after you turn it on, and turns itself off after 7 days.
  • Requests are kept for 14 days. Webhook deliveries are kept for 7 days when they succeeded, 14 days when they failed, and 30 days when they ran out of retries.
  • A request with an unknown key or no credentials is not logged, because no account owns it. A refusal for a wrong secret on one of your keys is logged without its request body.
  • Firewall blocks, OAuth token requests, dashboard traffic and embedded widget traffic are not logged.

The logs are visible to team members with access to the developer tools. Payloads contain the contact data you sent, so grant that access with care.

I got a 202 but nothing happened

Likely cause. A 202 means the request was queued, not sent. The result arrives later, and it went somewhere you aren't listening:

  • You have no webhook for the channel's status event. Without one, a result reaches you only if the send had a callback_url.
  • Your callback_url or webhook route answered something other than 2xx, often 404 because the route doesn't accept POST. A 404 isn't retried on either channel, so that result is gone.
  • The key or secret was wrong. That failure (3007) goes to callback_url only, never to a webhook.
  • You retried with the same Idempotency-Key and body. The retry is skipped and produces no second result.

How to confirm. Search the message_id on Settings > API Logs. The Delivery column is the later result, often No Caller ID (4010: pass a phone_line_id) or Too Many Attempts while you test. The same rows are under Campaigns in the API entry (Show API send history is on by default).

An INVALID / Refused row, including one for a wrong secret (3007), shows the validation message that refused the send. No row means the key isn't yours, or the request is older than 14 days. Check webhooks on the Webhooks tab, and list them with GET /register/public/webhooks.

Fix. Make your callback and webhook routes accept POST and answer 200 quickly, before doing any work. Create a webhook for the status event of each channel you send on (see Results of your sends), then act on the reason_code as Outcomes describes. The checks that run after the 202 are in Send lifecycle.

403 when uploading media

Likely cause. The PUT to a signed upload URL sent a Content-Type header that differs from the content_type returned next to that URL, or the URL expired.

How to confirm. Compare your Content-Type with upload.mp3.content_type or upload.wav.content_type from the create response, character for character. Some HTTP clients add a charset or pick a type from the file name.

Fix. Send exactly the returned content_type, for example -H "Content-Type: audio/mpeg" with curl --data-binary. If the URL expired, refresh it. If the file is at a public URL, skip the upload and import it from the URL instead. See Signed upload.

Sends fail with 3001 after copying the sample values

Likely cause. 3001 (Audio file not valid) means the media_id isn't on your account. The ids in these docs, the OpenAPI examples and the Postman collection are placeholders.

Fix. Upload or import your file with Media and send the media_id from that response. Take phone_line_id from GET /phone/public/lines and voice_id from GET /voice/public/voices.

Voicemails fail with 3014 or 3040

Likely cause.

  • 3014 (Not allowed audio_url): audio_url isn't enabled on your account, or the send gave no audio.
  • 3040 (Test Numbers Only): your account is in testing mode, and the number isn't one of your test numbers.

audio_url is available on BYOC plans only and must be enabled by support. Contact support to enable it. If you're testing on a retail account before connecting your carrier, support can enable it for testing; while testing, voice sends go only to your test numbers. Otherwise, upload your file and send media_id, or use text to speech.

How to confirm. GET /register/public/integration-readiness returns audio_url_allowed, test_numbers_only and test_numbers.

Fix. For 3014, send media_id or text to speech. For 3040, add the number under test numbers on the Dialing rules page, or finish connecting your carrier. See Test on retail, then go live on BYOC.

No webhook arrives

Likely cause.

  • No webhook lists the event. Check each webhook's event_types against the event you expect, or use ["*"] to receive every event.
  • Your endpoint didn't answer 2xx within 5 seconds, or answered a 4xx, which isn't retried.
  • Deliveries to your endpoint are paused after repeated failures. Events during a pause are dropped.
  • The URL resolves to a private or loopback address, which is never called.

How to confirm. Open the Webhooks tab of your API logs. A delivery there shows the status code your server answered and how long it took. Compare the event_types in GET /register/public/webhooks with the event's name in GET /register/public/events. Check your server logs for requests with an X-Attempt header, and how long you took to answer them.

Fix. Create a webhook that lists the event, or update an existing one with PUT /register/public/webhooks/{id} (event_types replaces the whole set, so include the events it already receives). Answer 2xx first and do the work afterwards. After fixing a failing endpoint, reconcile missed results from the API. See Endpoint pauses.

A webhook arrives but the signature doesn't verify

Likely cause.

  • You verify the parsed JSON instead of the raw request bytes.
  • You use the wrong secret. Each webhook has its own, and rotating a webhook's secret stops the old one verifying at once.
  • You treat X-Timestamp as milliseconds. It is in seconds.
  • Your server clock is more than 5 minutes off, so a fresh delivery looks old.

How to confirm. Fetch GET /register/public/account/webhook-signing-secret and compare the secret of the webhook that delivered it (match on webhook_id or event_types) with the one your verifier uses. A receiver that serves several webhooks should accept a signature from any of their secrets. Log the raw body and the X-Signature and X-Timestamp headers.

Fix. Use the samples in Verify the signature. Fix this quickly: five rejections in a row pause deliveries to your endpoint.

The voicemail shows success but the contact says they didn't get it

Likely cause. reason_code 0 means the message was left in the mailbox that answered. From there the contact's carrier delivers it, which can take up to 24 hours, and some carriers filter voicemails as spam. That part is outside our control. Otherwise the contact hasn't checked their voicemail, or the number reaches someone else's mailbox, for example after it was reassigned.

How to confirm. Open the result's proof_of_delivery_url and listen to the greeting before your message. Check that to in the status event is the number you meant to reach.

Fix. If the greeting belongs to someone else, update the contact's number. If it's theirs, the message was left in their mailbox; give the carrier up to 24 hours. See Proof of delivery.

Calls fail with 4003

Likely cause. The contact's number was temporarily unreachable. Often their phone carrier is having network problems, which Drop Cowboy can't fix.

How to confirm. Read reason_code on the status event. A few 4003 results spread across carriers are normal.

Fix. Try the call again later. If many sends fail with 4003 at once, contact support with a drop_id.

Likely cause. The body's error tells you which case it is:

  • not_ready: the recording isn't stored yet. The status event can arrive before it is.
  • not_found: the link is wrong (for example cut off when copied), or the voicemail is more than 7 days old, so proof of delivery is no longer available.

How to confirm. Read error and the Retry-After header on the response.

Fix. For not_ready, retry after Retry-After seconds, or subscribe to contact.rvm.receipt, which fires once the recording is ready. For an expired link (410 expired), get a new one with GET /campaign/public/deliveries/{drop_id}/receipt within 7 days of the voicemail. After 7 days proof of delivery is no longer available; keep your own copy if you need it longer. See Keep the recording.

A result has no proof of delivery

Likely cause. A result has it when a voicemail system took the call: a ringless voicemail, voice broadcast or AI call with reason_code 0, 4001 or 4002. A voice broadcast a person picked up has no recording, and an AI call a person picked up has one only when the agent's Record calls setting is on. Texts and emails have none. Proof of delivery is available for 7 days after the call.

How to confirm. Check reason_code, campaign_type and the time of the status event.

Fix. For other outcomes there's nothing to fetch. For an eligible result under 7 days old with no link, request one with GET /campaign/public/deliveries/{drop_id}/receipt. If that answers 404, contact support with the drop_id.

Every test send fails with 4013

Likely cause. Sending to your own number again and again reaches the contact frequency limit, 3 attempts in 3 days by default.

How to confirm. The 4013 status event carries frequency_limit, with attempts_in_window at or above max_attempts.

Fix. Add your numbers as test numbers on the Dialing rules page. They skip the limit. See Test numbers.

Texts fail with 6009 or 3029

Likely cause.

  • 6009 (Unregistered Brand): your account requires a registered brand, and the send had no brand_id, or its brand_id isn't a valid id.
  • 3029 (Phone Line Has No SMS Campaign): the phone_line_id you sent from isn't attached to a registered texting campaign.

How to confirm. For 3029, GET /phone/public/lines/{line_id} returns campaign_id: null for the line.

Fix. For 6009, pass the brand_id of your registered brand (GET /automation/public/brands), or register a brand and wait for approval. For 3029, attach the line to an approved texting campaign in the dashboard, or send from a line that has one. See Texts.

Texts outside business hours fail with 4011

Likely cause. Texts sent outside the contact's allowed hours fail with 4011 (TCPA Hours) instead of waiting. The window follows federal and state-specific calling hours in the contact's time zone.

How to confirm. Compare the send time with the contact's local time.

Fix. Send inside the window, with a new Idempotency-Key. Schedule campaigns for business hours. Voice sends are held until the window opens instead. See Calling hours.

MMS fails

Likely cause. Codes 3032 to 3039 are about the media on a text:

Code Cause Fix
3032 media_urls or media_ids malformed, more than 10 files, media with template_id, or media on a voice route Fix the request
3033 A media_id isn't on your account, was deleted, or has no uploaded file Use an id from GET /media/public/media
3034 A media URL didn't answer 200 in time, or redirected Host the file at a public https URL that answers directly, then retry
3035 A file is over 1 MiB, or the files total over 5 MiB Make the files smaller
3036 A file isn't JPEG, PNG, GIF, WAV or MP3, judged by its bytes Convert the file
3037 The malware scan flagged a file Don't send the file
3038 The malware scan didn't finish in time Retry shortly
3039 The malware scan failed Retry

How to confirm. Read reason_code on the contact.sms.status event or callback_url body.

Fix. As in the table. See MMS.

A voicemail fails with 4001 or 4002

Likely cause. The call reached the contact's mailbox, but it isn't set up (4001) or is full (4002), so no message could be left.

How to confirm. The result's proof of delivery recording plays the carrier's announcement.

Fix. Retrying the voicemail won't help until the contact sets up or clears their mailbox. Reach them on another channel they've agreed to, after checking their consent for it, for example a text.

Sends fail with 3000 or 5001

Likely cause.

  • 3000 (No Funds): your balance is empty.
  • 5001 (Payment Required): a subscription payment failed. It stops every channel, not only email.

How to confirm. Check GET /campaign/public/balance. For 5001, check the Billing page in the dashboard.

Fix. For 3000, add funds or turn on auto-recharge, then resend. For 5001, update the card on the Billing page, then resend. See Balance.

A campaign doesn't start

Likely cause.

  • It's waiting for compliance review (approved: false).
  • It was never started or scheduled (campaign_data.status is not_started).
  • It stopped because the balance ran out (campaign_data.status is insufficient_credit).
  • It's paused. A campaign that was sending pauses itself when an edit to its message, audio, lists or sending numbers sends it back to review.

How to confirm. GET /campaign/public/campaigns/{id} and read approved and campaign_data.status. A start that returns approved: false and started: false means the campaign is in review.

Fix. Create campaigns ahead of time so review can finish, and start them again once approved is true. Start one with POST /campaign/public/campaigns/{id}/start; a started: false answer means nothing was sent. For insufficient_credit, add funds, then start it again. See Campaigns.

Email isn't sent

Likely cause.

  • The send answered 200 with data.success: false, for example because the account has no verified sending domain.
  • The send answered 403: the key lacks email:send, or your plan doesn't include email.
  • The send succeeded, then the email was stopped by your do-not-contact list, an opt-out, missing email consent, the email frequency cap or a daily send limit.

How to confirm. Read data.success and error on the response. For a campaign email, read reason_code on contact.email.status. An email sent with POST /email/public/email that was stopped gets no delivered event.

Fix. Verify a sending domain and create a mailbox on it. Record email consent where your account requires it. Wait out the frequency cap, or add your own addresses as test email addresses on the Dialing rules page. See Email and Email-specific outcomes.


While Drop Cowboy provides tools to support compliance efforts, customers remain solely responsible for obtaining proper consent, maintaining opt-out lists, and complying with all federal and state telemarketing regulations. Consult with your legal counsel to ensure your specific use case and consent mechanisms comply with applicable laws.

This information is for educational purposes only and does not constitute legal advice. Regulations vary by jurisdiction and use case. Always consult with qualified legal counsel to ensure your specific practices comply with applicable federal and state laws.