Error Codes

All errors are returned as JSON with a descriptive message field.

HTTP status codes

Error response shape

{
  "statusCode": 400,
  "message": "Template \"unknown_template\" not found or not approved for this phone number",
  "error": "Bad Request"
}

Common errors

401 Unauthorized

Your API key is missing or invalid. Make sure you are passing the key as:

Authorization: Bearer bh_live_xxxxxxxxxxxx

403 Forbidden

The phone number ID you provided does not belong to your organization. Fetch your phone numbers from /v1/whatsapp/phone_numbers and use the id field.

404 Not Found

The template name or phone number ID was not found. Common causes:

• Using the phone number itself instead of the phone number id
• Template name typo — use the exact name field from the templates endpoint
• Template is not yet approved in Meta Business Manager

400 Bad Request — both media_id and media_url provided

Only one of media_id or media_url can be provided per send request. Remove one of them.