Skip to content

Error Codes ​

Each API group answers errors in its own shape (for compatibility with the previous API). This page collects every shape and message in one place.

Error shapes ​

#Used byHTTP statusBody shape
AAuthentication, Idempotency-KeyPer error (401/403/400/409/500){"error": "message"}
B/sms/*, rate limitsPer error{"error": {"statusCode": "...", "description": "...", "message": "..."}}
C/OTP/*Per error (some cases are 200 — see below){"error": {"code": "...", "message": "...", "description": "..."}}
D/Person, /Tag, /Blacklist, /Consent, /lineAlways 200{"status": <number>, "description": "..."}
E/shorten/*Per error{"status": <number>, "description": "..."}

WARNING

Group D answers HTTP 200 even on errors. Always check status in the body (200 = success).

HTTP statuses ​

HTTPMeaning
200Success (group D and some OTP cases need a body check)
302Short-link redirect /s/:code
400Invalid request
401Authentication failed
402Insufficient credit (prepaid accounts)
403Not allowed: IP not allowed, account suspended, service disabled, sender not approved
404Not found
409A request with the same Idempotency-Key is still running
429Rate limit exceeded
500Server error — safe to retry

Authentication (shape A) ​

See the full table in Authentication. Example:

json
{ "error": "invalid api key" }

Rate limit (shape B) ​

HTTPstatusCodemessagedescription
429429TOO_MANY_REQUESTSrate limit exceeded: max <N> requests per second per <IP|account|API key>

Comes with the header Retry-After: 1.

Idempotency-Key (shape A) ​

HTTPerror
400invalid Idempotency-Key
409request with this Idempotency-Key is in progress

Send SMS — /sms/send, /sms/preview (shape B) ​

Validation (HTTP 400, message = BAD_REQUEST) ​

descriptionCause
Invalid request bodyInvalid JSON or a required field is missing (messages, from, destinations, to, text)
Messages not foundmessages is empty
Destinations not founddestinations is empty or a to is empty
Text not foundtext is empty
sender not foundfrom is empty
sendAt must be in RFC3339 format (e.g. 2026-04-10T09:00:00+07:00)sendAt has the wrong format
Text too long: <n> characters (max 1600)Message longer than 1,600 characters (/sms/send only)
Too many destinations: <n> (max 1000 per request)More than 1,000 destinations in total (/sms/send only)

Account, credit and sender checks (/sms/send) ​

HTTPstatusCodemessagedescription
403403ACCOUNT_INACTIVEaccount is inactive
403403ACCOUNT_HELDaccount is on credit hold
403403SERVICE_NOT_ALLOWEDAPI sending is not enabled for this account
402402INSUFFICIENT_CREDITinsufficient credit: required <x>, available <y>
403101INVALID_SENDERsender '<from>' not authorized for this account
403102INVALID_DOMAINshorten URL domain '<domain>' not authorized for this account
500500INTERNAL_ERRORFailed to validate send request
500500INTERNAL_ERRORFailed to validate shorten URL domain
500500QUEUE_PUBLISH_FAILEDFailed to enqueue SMS for delivery — nothing was accepted; safe to retry (use an Idempotency-Key)

INSUFFICIENT_CREDIT applies to prepaid accounts only. Required credit counts sendable destinations only.

Per-destination status in details[].status ​

A successful request (HTTP 200) may still reject some numbers — REJECTED numbers are neither sent nor charged.

codenamedescription
101PENDINGPending -Message has been accepted by the system
402REJECTEDInvalid number - phone number formatted incorrectly
403REJECTEDNumber is blacklisted
SUPPRESSEDREJECTEDRecipient has opted out of non-OTP SMS
NO_CONSENTREJECTEDNo consent from recipient for this account

Other SMS — /sms/senderlist, /sms/loginfo (shape B) ​

HTTPstatusCodemessagedescription
401401UNAUTHORIZEDInvalid account
404404NOT_FOUNDAccount not found
500500INTERNAL_ERRORFailed to load sender list / Failed to query SMS logs

OTP — /OTP/* (shape C) ​

HTTPcodemessagedescription
400400BAD_REQUESTInvalid request body
403403ACCOUNT_INACTIVEaccount is inactive
403403ACCOUNT_HELDaccount is on credit hold
403403SERVICE_NOT_ALLOWEDOTP is not enabled for this account
402402INSUFFICIENT_CREDITinsufficient credit: required 1.00, available <y>
404404OTP_CONFIG_NOT_FOUNDOTP config not found for this account
404404OTP_NOT_FOUNDOTP not found for this account
500500INTERNAL_SERVER_ERRORFailed to validate OTP request / Failed to verify OTP
200500INTERNAL_SERVER_ERRORFailed to process OTP request
200500SMS_SEND_FAILEDFailed to send OTP SMS
200400RESEND_FAILEDFailed to resend OTP

WARNING

The last three rows answer HTTP 200 with an error in the body — always check for an error or success field.

Verification (/OTP/verifyotp) answers HTTP 200 and reports the result in status.

status.codestatus.messageMeaning
200VERIFIEDCode is correct
410EXPIREDCode has expired
429MAX_ATTEMPTSToo many wrong attempts
401INVALID_CODEWrong code (description gives the attempts left)
statusMeaningExample description
200SuccessPerson deleted., Tag assigned.
400Missing or invalid inputfirstName is required., personId is required., mobile is required., Invalid mobile number., mobile, consentType, and granted are required., tokenId and message are required.
401No account resolved from the credentialUnauthorized.
403LINE token disabledLINE token is inactive.
404Not foundPerson not found., Tag not found., Destination not found., No consent record found., LINE token not found.
500Server errorFailed to create person., Failed to query tags., etc.
501Feature not available yet<feature> is not yet available on this API.
503LINE service unavailableLINE gateway not configured.

URL Shortener — /shorten/* (shape E) ​

HTTPdescription
400invalid request body
400URL must use http or https scheme
400page and pageSize must be positive integers
404short URL not found
500failed to create short URL / failed to query URLs

Handling errors ​

CaseWhat to do
400, 401, 402, 403, 404Fix the request or account setup first — retrying gives the same result
409Wait 1–2 seconds, retry with the same Idempotency-Key
429Wait for Retry-After, then retry
500Retry with exponential backoff — use an Idempotency-Key on sends to avoid duplicates