API reference

Error codes

Every error QuickAuth returns, what causes it and how to fix it. Your code should branch on errorCode; the message is written for people and can change.

Error response

HTTP/1.1 400 Bad Request
X-Request-Id: 9b2f0c7e1a6d4c3b8e5f2a1d0c9b8a7e

{
  "errorCode": "OTP_EXPIRED",
  "message": "OTP has expired. Please initiate a new request.",
  "requestId": "9b2f0c7e1a6d4c3b8e5f2a1d0c9b8a7e"
}

errorCode — one of the codes below. Stable; safe to branch on.
message — a human-readable explanation, often naming the field to fix.
requestId — our reference for this call. Include it when you contact support.

Not every failure is an HTTP error

Some outcomes are normal 200 responses you must check: a wrong OTP returns verified: false, and a WhatsApp message WhatsApp refuses returns status: FAILED (or SKIPPED for opted-out users) with an errorMessage.

Problems with the request

Fix the request and send it again. Retrying it unchanged gives the same error.

INVALID_REQUEST400401404405409413

The request was not accepted as sent. The message says exactly what to change. Common causes:

400 — a required field is missing or invalid (e.g. phone: phone must be E.164), a phone number is too short or not a mobile, an SMS template or sender id is not registered, or template variables do not fit.
401 — Confirm a verification received an idToken that is invalid, expired or from another account.
404 — the id does not exist on your account (message, campaign, lead), or the URL is wrong.
405 — wrong HTTP method for this URL (e.g. GET instead of POST).
409 — the request is valid but cannot be done right now: the 24-hour reply window is closed, WhatsApp has restricted the template, no number can send it, or another agent just claimed the lead.
413 — deviceInfo is larger than 4 KB.

What to doRead the message, correct the request, then retry.

INVALID_MODE400

mode on Send an OTP is not OTP or OAUTH.

What to doUse OTP.

CHANNEL_REQUIRED400

OAUTH mode was requested without a channel.

What to doSend channel: WHATSAPP or TRUECALLER.

INVALID_CHANNEL400

The channel does not support OAUTH mode.

What to doUse WHATSAPP or TRUECALLER, or switch to OTP.

REDIRECT_URI_REQUIRED400

OAUTH mode was requested without a redirectUri.

What to doSend redirectUri.

Authentication

Your credentials were missing, wrong or not allowed. Do not retry until they are fixed.

INVALID_CLIENT_CREDENTIALS401

One of:

X-Client-Id / X-Client-Secret missing, unknown or wrong — often an old secret after someone clicked Regenerate.
The publishable key (X-QuickAuth-Key) is unknown or revoked.
App restriction is on and this app’s package name, bundle id or website origin is not registered for the key.
The SDK session token is missing, malformed or expired (they last 1 hour).

What to doCopy fresh credentials from Dashboard → Settings, register the app for the key, or mint a new session token.

CLIENT_INACTIVE401

Your QuickAuth account has been deactivated.

What to doContact QuickAuth support.

OTP verification

The verification can no longer be completed. Start a new one.

OTP_EXPIRED400

The code is older than your expiry setting (default 5 minutes).

What to doSend a new OTP and ask the user to enter the new code.

MAX_ATTEMPTS_EXCEEDED400

Too many wrong codes for this verification (default 3).

What to doSend a new OTP. Consider a short wait first to slow down guessing.

TRANSACTION_NOT_FOUND400

No verification with this requestId / orderId on your account.

What to doCheck you are sending the id from Send an OTP, with the same account’s credentials.

Templates, senders and numbers

Something needed for this send is not set up in your dashboard.

TEMPLATE_NOT_FOUND400404409

400 (OTP) — no default OTP template for this channel, the templateId you passed is not an active template, or your WhatsApp authentication template is not approved.
404 (WhatsApp) — no template with that templateId on your account; for campaigns, also a template not approved yet.
409 (WhatsApp single send) — the template exists but is not approved yet.

What to doSet a default template in the dashboard, use the 32-character templateId (not the name), or wait for approval.

DLT_SENDER_NOT_FOUND400

OTP over SMS: no default sender id (header) is set, or the header you passed is not registered.

What to doAdd a sender id under DLT in the dashboard, or pass a registered header.

DLT_REGISTRATION_SUSPENDED403

Your DLT registration is suspended, so OTP SMS cannot be sent.

What to doContact QuickAuth support. Meanwhile use WhatsApp as the OTP channel.

INCOMPLETE_TEMPLATE_CONFIG400

Your OTP SMS template has a variable slot with no value configured.

What to doOpen the template in the dashboard and save a value or the OTP for every slot.

WHATSAPP_CONNECT_FAILED409

Creating a WhatsApp template needs a connected, healthy WhatsApp number and there is none.

What to doReconnect your number under Connect WhatsApp in the dashboard.

Balance and billing

Nothing was sent and nothing was charged.

INSUFFICIENT_BALANCE402

Your wallet is empty or does not cover this message or campaign, or a postpaid account reached its credit limit.

What to doAdd funds (Dashboard → Billing), or contact us to raise your limit.

INSUFFICIENT_SMS_BALANCE402

Prepaid SMS credits are at 0.

What to doRecharge SMS credits.

INSUFFICIENT_WHATSAPP_BALANCE402

Prepaid WhatsApp credits are at 0, or fewer than the campaign needs.

What to doRecharge WhatsApp credits.

BILLING_NOT_CONFIGURED402

Billing has not been set up on your account yet.

What to doContact QuickAuth support.

INTERNATIONAL_PRICE_UNAVAILABLE422

The recipient is outside India and there is no WhatsApp price for their country on your account.

What to doContact QuickAuth support to enable that country.

Rate limits

Slow down and retry later with exponential backoff.

RATE_LIMIT_EXCEEDED429

More than 10 new OTPs to the same number in an hour (your account’s limit), or a publishable key went over 1,000 calls an hour per platform (300 from browsers).

What to doFor a single number, tell the user to try again later. For a key, spread traffic or use session tokens.

Channel and server errors

The problem is on the sending side, not in your request.

PROVIDER_ERROR409422429500502

409 — no connected number for the channel, or WhatsApp disabled it. Reconnect in the dashboard.
422 — WhatsApp rejected the message content.
429 — WhatsApp is rate-limiting your number. Retry later.
500 — the SMS operator refused the message. Retry (with the same idempotencyKey).
502 — WhatsApp failed temporarily. Retry with backoff.

What to doFollow the advice for the status above.

INTERNAL_ERROR500

Something went wrong on our side. A body that is not valid JSON, a missing Content-Type: application/json header, or a lower-case enum value (e.g. "sms" where "SMS" is expected) currently also produces this error.

What to doCheck the request is valid JSON with upper-case enums, then retry with backoff. If it continues, send us the requestId.

WhatsApp delivery failures

When WhatsApp does not deliver a message, the send response (errorMessage) or the delivery.failed webhook (errorCode, reason) carries WhatsApp’s own code. The ones you will see most:

Code	Meaning and what to do
`131026`	Message undeliverable — the number is not on WhatsApp, or the user is on an old app version.
`131047`	More than 24 hours since the customer last wrote. Send a template instead of a free-form reply.
`131049`	WhatsApp limited marketing messages to this user to protect their experience. Try later; do not resend at once.
`131050`	The user has stopped marketing messages from businesses.
`130429 / 131056`	Too many messages too fast, overall or to the same user. Slow down.
`132001`	Template does not exist in this language on the sending number.
`132015 / 132016`	Template paused or disabled by WhatsApp for low quality. Edit it or use another.

Failed messages are not charged.

WebEngage responses

The WebEngage endpoint answers in WebEngage’s format: {"status": "whatsapp_rejected", "statusCode": 2001, "message": "…"}.

statusCode	HTTP	Meaning
`0`	200	Accepted (also for a repeat of the same messageId).
`2000`	402	Balance or billing problem — wallet, credits or credit limit.
`2001`	400	Rejected: missing messageId / toNumber / template, unknown template name or language, unknown fromNumber, wrong number of variables, bad media URL or button value, template not approved.
`2001`	401	Invalid or missing QuickAuth credentials in the WebEngage provider settings.
`2015`	429	Too many requests (over 50 per second), or a temporary server error. WebEngage retries automatically.

CleverTap responses

The CleverTap endpoint always returns HTTP 200 and puts the result in the body: {"status": "failure", "error": {"code": 2001, "message": "…"}}.

code	Meaning
`2000`	Invalid credentials or inactive account.
`2001`	Template problem: unknown template name or language, wrong variables, not approved, missing header media or bad button value.
`2002`	The to number is missing.
`2003`	Balance or billing problem.
`2004`	Anything else: freeform (non-template) message, missing msgId, unknown wabaNumber, malformed request, or a server error.