Troubleshooting: KakaoTalk Alimtalk 422 and Friendtalk body rejects

A KakaoTalk send that fails before it leaves Orbit almost always trips one of the two content gates Kakao enforces on Biz Message: an Alimtalk send with no approved template code, or a Friendtalk send with no body. Both come back as 422 VALIDATION_ERROR on the error envelope, and both are deterministic — retrying the same request body fails identically, and no reconnect fixes either gate. This page covers both gates plus the one credential variant (CHANNEL_NOT_CONFIGURED); credential precedence is on Troubleshooting: WeChat and Zalo credential resolution. In the source Kakao channel page, these are the send-shape errors. The two message types are enforced server-side (channel → alimtalk is default; metadata.kakao_message_type selects friendtalk).

Symptom map

Symptom variant	`kakao_message_type`	Cause	Fix
422 `VALIDATION_ERROR` on a campaign Alimtalk send	`alimtalk` (default)	`message_template` (template_name) missing or not approved by the Kakao reseller	Select an approved Alimtalk template code in `message_template`; friendtalk is the only type that takes a free-form body
422 `VALIDATION_ERROR` on a direct send with `body` only	`friendtalk` unset (defaulting to `alimtalk`)	The send omitted `metadata.kakao_message_type`, so it went to the Alimtalk gate — which rejects a free-form `body` at once	Set `metadata.kakao_message_type: "friendtalk"` when you intend the free-form path
422 `VALIDATION_ERROR` on a Friendtalk send	`friendtalk`	`body` missing or empty	Pass a non-empty `body` — Friendtalk is free-form but empty is not free-form
503 `CHANNEL_NOT_CONFIGURED`	either	No KakaoTalk credentials for the organization and no platform default	Connect under Settings → Channels → KakaoTalk (app key, secret key, sender key)

Alimtalk gate — the template name must be approved

Alimtalk (알림톡) is a transactional-notification class in Korea that Kakao requires you to pre-approve. The API rejects the send at validation time when message_template (the campaign-body field carrying the template code) is missing, or when the code is not one your KakaoTalk reseller approved for your sender profile (발신프로필). Full-error sample, from a campaign launch:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "kakao alimtalk requires template_name — select an approved KakaoTalk template code"
  },
  "meta": {
    "request_id": "req_xyz789",
    "timestamp": "2026-06-08T00:00:00Z"
  }
}

Resolution:

Ask your Kakao reseller for the approved template code for the sender profile your credentials hold.
In the campaign, set message_template to that exact code and fill its #{var} variables under variables.
Re-launch the campaign. The 422 is deterministic — a correct template code passes on the first retry.

Friendtalk gate — body is mandatory

Friendtalk (친구톡) is the free-form marketing channel for followers of your brand profile. The validation gate is one field: body must be non-empty. Optional on this type: a media_url image. Resolution:

Set metadata.kakao_message_type: "friendtalk" on the direct send.
Ensure body carries a non-empty value — whitespace alone fails the same gate.
Send to a follower; Kakao itself lets Friendtalk reach only accounts that added your channel as a friend.

The wrong-type trap

The most common Kakao 422 is a free-form send that went through the Alimtalk gate, because metadata.kakao_message_type was omitted and the client defaulted to alimtalk. The check sequence:

Grep the failing request: does it set metadata.kakao_message_type at all?
If it does not, and the body carries free-form body only, you hit the Alimtalk gate — which requires a template, not a body.
Either pass metadata.kakao_message_type: "friendtalk" with the free-form body, or pass an approved message_template through the campaigns API.

What not to try

Do not reconnect KakaoTalk credentials for a VALIDATION_ERROR. A 503 CHANNEL_NOT_CONFIGURED means credentials; a 422 means the request body. Re-pasting keys does not pass a content gate.
Do not retry the same body. Validation fails deterministically — the response already carried the code; fix the template or body, then retry.
Do not move a Friendtalk send through campaigns. Alimtalk goes through campaigns (template + variables); Friendtalk is the direct POST /api/v1/messages/kakao route with kakao_message_type: "friendtalk".

When to escalate

Open a support ticket when you pass an approved template code your reseller has verified, the body is non-empty, and the send still returns the same 422 — or when the campaign launch fails only from certain audience segments. Include:

The full message_template code exactly as entered in the request.
One request ID (meta.request_id) from the rejection.
The sender profile / channel key your Kakao reseller holds (so support can confirm it matches the connected credentials).

Reference

Troubleshooting: KakaoTalk Alimtalk 422 and Friendtalk body rejects

Troubleshooting: KakaoTalk Alimtalk 422 and Friendtalk body rejects

Symptom map

Alimtalk gate — the template name must be approved

Friendtalk gate — body is mandatory

The wrong-type trap

What not to try

When to escalate

See also

​Troubleshooting: KakaoTalk Alimtalk 422 and Friendtalk body rejects

​Symptom map

​Alimtalk gate — the template name must be approved

​Friendtalk gate — body is mandatory

​The wrong-type trap

​What not to try

​When to escalate

​See also

Troubleshooting: KakaoTalk Alimtalk 422 and Friendtalk body rejects

Symptom map

Alimtalk gate — the template name must be approved

Friendtalk gate — body is mandatory

The wrong-type trap

What not to try

When to escalate

See also