API reference

Understand and resolve an API error

Errors include error, message, request_id and doc_url. Validation errors also identify the field in param or details. Keep the request ID for support; never share your key.

Scroll the table horizontally to read error details.

Error codes, HTTP statuses and recovery messages
Error code	HTTP	Meaning and recovery
`resource_erased`	409	Resource erased This request refers to erased data and cannot be replayed.
`resource_busy`	409	Work in progress Background work is using this workspace. Wait for it to finish, then retry the erasure.
`campaign_state_conflict`	409	Campaign state conflict This campaign cannot be changed in its current state.
`otp_rate_limited`	429	Too many codes Wait before requesting another verification code for this phone number.
`api_not_enabled`	403	API access not enabled Live API access is not enabled for this workspace during the private beta. You can use a test key while requesting access.
`merchant_agreement_required`	403	Merchant agreement required A workspace owner must accept the current Data Processing Addendum in Buddy before this workspace can use the API.
`invalid_request`	400	Invalid request Some fields are missing or invalid. See details.errors for each one.
`invalid_json`	400	Invalid JSON The request body is not valid JSON.
`unknown_field`	400	Unknown field The request has a field this endpoint does not accept. Check the spelling.
`invalid_phone`	400	Invalid phone number Use an international number in E.164 format, starting with + and the country code.
`invalid_id`	400	Invalid ID This ID is not in the expected format.
`invalid_cursor`	400	Invalid cursor The cursor is not valid. Use the next_cursor value from the previous page.
`invalid_idempotency_key`	400	Invalid idempotency key Idempotency-Key must be 1 to 255 visible ASCII characters.
`idempotency_key_required`	400	Idempotency key required This endpoint needs an Idempotency-Key header so a retry can never act twice.
`template_language_mismatch`	422	Template language mismatch This template exists in another language. Use one of the languages in details.languages.
`language_required`	400	Language required This template exists in more than one language. Pass the language you want.
`template_variables_mismatch`	400	Template variables mismatch The variables do not match the template's parameters.
`unauthorized`	401	Unauthorized Send a valid API key as a bearer token: Authorization: Bearer bd_live_...
`api_key_expired`	401	API key expired This API key has expired. Create or roll a key in your Buddy settings.
`api_key_revoked`	401	API key revoked This API key was revoked. Create a new key in your Buddy settings.
`token_expired`	401	Access token expired This access token has expired. Use your refresh token to get a new one.
`insufficient_scope`	403	Insufficient scope This key does not have the scope this endpoint needs. See details.required.
`not_found`	404	Not found Nothing was found with that ID.
`subscriber_not_found`	404	Subscriber not found No subscriber with that ID, phone or external ID exists in this workspace and mode.
`template_not_found`	404	Template not found No template with that ID or name exists in this workspace.
`message_not_found`	404	Message not found No message with that ID exists in this workspace and mode.
`campaign_not_found`	404	Campaign not found No campaign with that ID exists in this workspace.
`webhook_endpoint_not_found`	404	Webhook endpoint not found No webhook endpoint with that ID exists in this workspace and mode.
`delivery_not_found`	404	Delivery not found No delivery with that ID exists for this webhook endpoint.
`subscriber_opted_out`	409	Subscriber opted out This person opted out. Only they can opt back in, through your opt-in page or form.
`external_id_taken`	409	External ID in use Another subscriber already has this external_id.
`consent_required`	409	Consent required Marketing messages need a subscriber who opted in.
`whatsapp_not_connected`	409	WhatsApp not connected Connect a WhatsApp number in Buddy before sending with a live key.
`idempotency_key_reused`	409	Idempotency key reused This Idempotency-Key was used with a different request. Use a new key for a new request.
`request_in_progress`	409	Request in progress A request with this Idempotency-Key is running or awaiting reconciliation. Retry with the same key. If this persists, contact support with the request ID; do not use a new key.
`webhook_endpoint_disabled`	409	Webhook endpoint disabled This webhook endpoint is disabled. Enable it before sending to it.
`payload_too_large`	413	Payload too large The request body is larger than 256 KB.
`unsupported_media_type`	415	Unsupported media type Send the request body as JSON with Content-Type: application/json.
`template_not_approved`	422	Template not approved This template is not approved by WhatsApp, or it is paused.
`transactional_flag_required`	422	Transactional flag required Sending a utility template to someone who is not a subscriber needs "transactional": true.
`outside_service_window`	422	Outside the 24-hour window Free text can only be sent within 24 hours of the person's last message. Use a template.
`url_not_allowed`	422	URL not allowed The URL must use https and point to a public address.
`otp_invalid`	422	Code not valid The code is not correct.
`otp_expired`	422	Code expired The code has expired. Send a new one.
`otp_attempts_exceeded`	422	Too many attempts Too many wrong codes. Send a new one.
`rate_limited`	429	Rate limited Too many requests. Wait for the time in Retry-After, then try again.
`internal_error`	500	Internal error Something went wrong on our side. Retry, and quote the request_id if it keeps happening.
`service_unavailable`	503	Service unavailable The service is briefly unavailable. Retry in a moment.
`webhook_url_invalid`	422	Webhook URL not allowed The webhook URL must use https and resolve to a public address. See details.reason.
`webhook_endpoint_limit_reached`	409	Webhook endpoint limit reached This workspace has the most webhook endpoints allowed in this mode. Delete one you no longer use.