Responses & Error Codes

Response envelope

The outbound, settings, and retrieval APIs respond with a common envelope.

{ "ok": true, "code": "0", "message": null }

Field	Description
ok	Whether the request succeeded (boolean)
code	Result code string. "0" on success; see the table below on failure
message	Human-readable description (may be null on success)
data	(settings · retrieval) Kakao's original data
url / name / size	(upload) Upload result

HTTP status & codes

HTTP	code	Meaning	Action
401	—	Token missing / invalid	Check the API Key
403	FORBIDDEN	Insufficient permission (BrandWrite required)	Raise the scope
403	NO_BRAND_SCOPE	Key not authorized for this brand	Check brandKey
404	NO_BRAND	Brand does not exist	Check brandKey
400	EMPTY	Required field missing	Check the request body
400	BAD_RICH	Failed to parse rich JSON	Validate the rich string
400	NOT_MULTIPART	Upload is not multipart	Check Content-Type
400	NO_FILE	No upload file	Check the file part
400	UNSUPPORTED_IMAGE	The upload/image file is not a jpg, png or gif image (including renamed or corrupted files)	Save as jpg, png or gif and upload again
413	IMAGE_TOO_LARGE	The image is over 5MB (5,242,880 bytes) — upload/image (rich); for Send attachments it is reported per item	Reduce the size and upload again
400	BAD_URL	The imageUrl of send/image is not an image uploaded to Kakao (external image URLs cannot be sent directly)	Upload with upload/image (imageType=plain) first and use the returned url
503	NO_PERSISTENCE	Inbound persistence disabled (retrieval fallback)	Retry shortly
402	QUOTA_EXHAUSTED	All consultations for this subscription cycle are used — nothing was sent	Pay for the subscription, then send again. upgradeToPlan in the response (when present) is a reference to a higher plan

Send failure codes (Kakao results)

When the request itself was processed but Kakao did not accept the message, the HTTP status is 200 and the body has ok: false. Looking at the HTTP status alone would read as success — always decide on ok and code.

{ "ok": false, "code": "-502", "message": "이미 종료된 상담이라 전송되지 않았어요. 고객이 다시 메시지를 보내면 새 상담으로 이어져요.", "serial": "bw-1790921339104-ef60" }

• code — Kakao's result code, passed through unchanged (a negative number as a string). Use it as the branching key in your consultation system.
• message — not Kakao's raw text but a sentence an agent can read as-is (currently in Korean). You can show it on screen. Wording may change, so branch on code.
• A send that was not delivered (ok: false) does not count against your consultations. EXCEPTION, where delivery cannot be confirmed, may be counted.

code	Meaning	What your system should do	Retry
-502	Consultation session expired or missing — replying to a closed chat	Mark the chat as closed. Once the customer sends a new message (inbound message · reference), you can send again	✗
-511	Customer is blocked	Unblock (unblock), then send	✗
-508	The channel's chat feature is off	Turn chat on in the channel admin center, then send	✗
-501	Channel cannot take consultations (channel inactive · consultation talk not enabled)	Check the channel status	✗
-512	No valid consultation talk contract	Check channel settings	✗
-506	Message longer than 1,000 characters	Split it and send	After fixing
-505	File or image cannot be sent (format · size · aspect ratio)	Check the file — images: jpg · png · gif up to 5MB, width:height between 3:4 and 2:1	After fixing
-503	Malformed customer key (userKey)	Use the userKey received on the inbound webhook as-is	✗
-509 · -510	Malformed message (missing rich-envelope fields, wrong bubble type, etc.)	Check the rich envelope schema	After fixing
-504 · -520	Same request repeated in a short time	Send again shortly	✓ (delayed)
-400 · -500 · -507	Sender credential check failed	Retry shortly; contact support if it persists	✓ (delayed)
-600 · -601 · 500	Temporary Kakao error	Retry shortly (with increasing intervals)	✓
NO_CONFIG	The channel's sending setup is not complete	Check the channel connection status in TalkBridge Center	✗
EXCEPTION	Network error or timeout — delivery is unknown	It may already have reached the customer — resending can make them see the same text twice, so retry once only (only successful sends produce an agent echo, so the echo cannot tell you)	Once
Other codes	Kakao results not listed above	Follow the guidance in message (it includes 사유 코드: …, the reason code)	—

Knowing a session has ended in advance

To know before sending, watch the inbound webhook. When a session ends, a kind: "expired" (expired) or "ended" (ended) signal arrives. Sends to that chat come back as -502.

Attachment sends (/api/agent/send/attachments) return a result per item. The top-level ok is true if at least one item was sent, and each entry in results[] carries ok · code · message in the same format — resend only the items that failed.

Handling principles

• If ok is not true, branch on code before retrying. Authentication errors such as NO_BRAND_SCOPE and FORBIDDEN fail the same way on retry.
• For session-related failures (such as -502 expiry), retry after a new inbound event has resumed the session.
• Send failures arrive as HTTP 200 + ok: false — follow the Retry column of the send failure codes table. Codes marked ✗ fail the same way on retry.