API reference / Track results
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
- On the Requests tab, choose
request_idormessage_idnext to Find by ID, paste the value and search. - 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
202body 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_urlor webhook route answered something other than2xx, often404because the route doesn't acceptPOST. A404isn't retried on either channel, so that result is gone. - The key or secret was wrong. That failure (
3007) goes tocallback_urlonly, never to a webhook. - You retried with the same
Idempotency-Keyand 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_urlisn'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_typesagainst the event you expect, or use["*"]to receive every event. - Your endpoint didn't answer
2xxwithin 5 seconds, or answered a4xx, 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-Timestampas 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.
The proof of delivery link answers 404
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 nobrand_id, or itsbrand_idisn't a valid id.3029(Phone Line Has No SMS Campaign): thephone_line_idyou 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.statusisnot_started). - It stopped because the balance ran out (
campaign_data.statusisinsufficient_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
200withdata.success: false, for example because the account has no verified sending domain. - The send answered
403: the key lacksemail: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.