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 by | HTTP status | Body shape |
|---|---|---|---|
| A | Authentication, Idempotency-Key | Per error (401/403/400/409/500) | {"error": "message"} |
| B | /sms/*, rate limits | Per error | {"error": {"statusCode": "...", "description": "...", "message": "..."}} |
| C | /OTP/* | Per error (some cases are 200 — see below) | {"error": {"code": "...", "message": "...", "description": "..."}} |
| D | /Person, /Tag, /Blacklist, /Consent, /line | Always 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
| HTTP | Meaning |
|---|---|
| 200 | Success (group D and some OTP cases need a body check) |
| 302 | Short-link redirect /s/:code |
| 400 | Invalid request |
| 401 | Authentication failed |
| 402 | Insufficient credit (prepaid accounts) |
| 403 | Not allowed: IP not allowed, account suspended, service disabled, sender not approved |
| 404 | Not found |
| 409 | A request with the same Idempotency-Key is still running |
| 429 | Rate limit exceeded |
| 500 | Server error — safe to retry |
Authentication (shape A)
See the full table in Authentication. Example:
json
{ "error": "invalid api key" }Rate limit (shape B)
| HTTP | statusCode | message | description |
|---|---|---|---|
| 429 | 429 | TOO_MANY_REQUESTS | rate limit exceeded: max <N> requests per second per <IP|account|API key> |
Comes with the header Retry-After: 1.
Idempotency-Key (shape A)
| HTTP | error |
|---|---|
| 400 | invalid Idempotency-Key |
| 409 | request with this Idempotency-Key is in progress |
Send SMS — /sms/send, /sms/preview (shape B)
Validation (HTTP 400, message = BAD_REQUEST)
description | Cause |
|---|---|
Invalid request body | Invalid JSON or a required field is missing (messages, from, destinations, to, text) |
Messages not found | messages is empty |
Destinations not found | destinations is empty or a to is empty |
Text not found | text is empty |
sender not found | from 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)
| HTTP | statusCode | message | description |
|---|---|---|---|
| 403 | 403 | ACCOUNT_INACTIVE | account is inactive |
| 403 | 403 | ACCOUNT_HELD | account is on credit hold |
| 403 | 403 | SERVICE_NOT_ALLOWED | API sending is not enabled for this account |
| 402 | 402 | INSUFFICIENT_CREDIT | insufficient credit: required <x>, available <y> |
| 403 | 101 | INVALID_SENDER | sender '<from>' not authorized for this account |
| 403 | 102 | INVALID_DOMAIN | shorten URL domain '<domain>' not authorized for this account |
| 500 | 500 | INTERNAL_ERROR | Failed to validate send request |
| 500 | 500 | INTERNAL_ERROR | Failed to validate shorten URL domain |
| 500 | 500 | QUEUE_PUBLISH_FAILED | Failed 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.
code | name | description |
|---|---|---|
101 | PENDING | Pending -Message has been accepted by the system |
402 | REJECTED | Invalid number - phone number formatted incorrectly |
403 | REJECTED | Number is blacklisted |
SUPPRESSED | REJECTED | Recipient has opted out of non-OTP SMS |
NO_CONSENT | REJECTED | No consent from recipient for this account |
Other SMS — /sms/senderlist, /sms/loginfo (shape B)
| HTTP | statusCode | message | description |
|---|---|---|---|
| 401 | 401 | UNAUTHORIZED | Invalid account |
| 404 | 404 | NOT_FOUND | Account not found |
| 500 | 500 | INTERNAL_ERROR | Failed to load sender list / Failed to query SMS logs |
OTP — /OTP/* (shape C)
| HTTP | code | message | description |
|---|---|---|---|
| 400 | 400 | BAD_REQUEST | Invalid request body |
| 403 | 403 | ACCOUNT_INACTIVE | account is inactive |
| 403 | 403 | ACCOUNT_HELD | account is on credit hold |
| 403 | 403 | SERVICE_NOT_ALLOWED | OTP is not enabled for this account |
| 402 | 402 | INSUFFICIENT_CREDIT | insufficient credit: required 1.00, available <y> |
| 404 | 404 | OTP_CONFIG_NOT_FOUND | OTP config not found for this account |
| 404 | 404 | OTP_NOT_FOUND | OTP not found for this account |
| 500 | 500 | INTERNAL_SERVER_ERROR | Failed to validate OTP request / Failed to verify OTP |
| 200 | 500 | INTERNAL_SERVER_ERROR | Failed to process OTP request |
| 200 | 500 | SMS_SEND_FAILED | Failed to send OTP SMS |
| 200 | 400 | RESEND_FAILED | Failed 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.code | status.message | Meaning |
|---|---|---|
200 | VERIFIED | Code is correct |
410 | EXPIRED | Code has expired |
429 | MAX_ATTEMPTS | Too many wrong attempts |
401 | INVALID_CODE | Wrong code (description gives the attempts left) |
Contacts, Tags, Blacklist, Consent, LINE (shape D — always HTTP 200)
status | Meaning | Example description |
|---|---|---|
200 | Success | Person deleted., Tag assigned. |
400 | Missing or invalid input | firstName is required., personId is required., mobile is required., Invalid mobile number., mobile, consentType, and granted are required., tokenId and message are required. |
401 | No account resolved from the credential | Unauthorized. |
403 | LINE token disabled | LINE token is inactive. |
404 | Not found | Person not found., Tag not found., Destination not found., No consent record found., LINE token not found. |
500 | Server error | Failed to create person., Failed to query tags., etc. |
501 | Feature not available yet | <feature> is not yet available on this API. |
503 | LINE service unavailable | LINE gateway not configured. |
URL Shortener — /shorten/* (shape E)
| HTTP | description |
|---|---|
| 400 | invalid request body |
| 400 | URL must use http or https scheme |
| 400 | page and pageSize must be positive integers |
| 404 | short URL not found |
| 500 | failed to create short URL / failed to query URLs |
Handling errors
| Case | What to do |
|---|---|
| 400, 401, 402, 403, 404 | Fix the request or account setup first — retrying gives the same result |
| 409 | Wait 1–2 seconds, retry with the same Idempotency-Key |
| 429 | Wait for Retry-After, then retry |
| 500 | Retry with exponential backoff — use an Idempotency-Key on sends to avoid duplicates |
