Errors

The API key is missing, mistyped, revoked, or used from an address outside its allow-list. Send Authorization: Bearer <secret> with the full secret shown when the key was created.

The key was disabled in the console or by an administrator. Re-enable it or create a new key.

This key is configured to require signed requests. Turn on request signing in your SDK (the signing option) or add the X-Toutye-Key, -Timestamp, -Nonce and -Signature headers.

The signature did not match. Sign the exact bytes you send, with the path and query in canonical order, and keep your clock within 5 minutes of real time.

The nonce was already used. Every signed request needs a new random nonce; the SDKs generate one per attempt.

Signature checking is briefly unavailable. Retry after a short wait; nothing was processed.

Several failed sign-ins in a row: the next sign-in must include a solved challenge.

The challenge answer was rejected or expired. Solve a new challenge and sign in again.

The key or user lacks the permission (scope) this endpoint needs, or the resource belongs to another account or environment. Check the key's scopes and that a sandbox key is used with sandbox resources.

This action is sensitive and needs a fresh second-factor confirmation from a signed-in user. It cannot be done with an API key alone.

Your account requires a second person to approve this action. It has been queued for approval; it runs once approved.

A field is missing, has the wrong type or is out of range. details lists each problem as a field path and an issue.

No such resource in this account and environment. Check the SID, and that sandbox and live resources are not mixed.

This path exists, but does not support the requested HTTP method. Use a method listed in the Allow response header and the API reference; do not retry the same method.

The sender cannot send this kind of message (for example a Flow or a product message) until the capability is enabled on its WhatsApp Business Account.

The uploaded media is still being scanned or processed. Wait until its state is READY, then send.

The media failed the safety scan or is an unsupported type or size. Upload a different file.

This message type cannot be sent to that kind of address (for example a username instead of a phone number). Address the recipient by phone number.

The WhatsApp username is not in a valid format.

A per-message status callback must point at a webhook endpoint that has passed verification. Verify the endpoint first.

A template with this name was deleted recently; WhatsApp does not allow reusing the name for 30 days. Pick another name.

The WhatsApp Business Account has reached its template limit. Delete unused templates.

The Idempotency-Key was already used within 24 hours for a different request body or endpoint. Use a new key for a new request.

The first request with this key is still running. Wait a moment and retry with the same key; you will receive its result.

A rate limit was exceeded. Wait retryAfterSeconds, then retry. The RateLimit-Policy header names the limit you hit.

WhatsApp is throttling this sender. The message is retried automatically when queued; for direct calls, wait and retry.

The account is suspended, so it cannot send. The console explains why and what is needed to lift it.

The account has used the message allowance in its contracted plan for this period. Nothing was sent. Wait for the allowance to renew, or ask your account owner to change the plan.

The prepaid balance cannot cover this message. Top up the wallet or change the billing mode.

The sender (phone number) is not connected or verified yet. Finish onboarding, or use a sender whose status is CONNECTED.

WhatsApp has restricted this number, usually after quality problems. Sending resumes when the restriction ends.

The number may not send template messages for now. Replies inside an open service window still work.

The template does not exist in that language, or WhatsApp has not approved it. Check its name, language and status.

WhatsApp paused the template because recipients reported or blocked it. Edit it or wait for the pause to end.

Free-form messages (text, media, interactive) are allowed only within 24 hours of the customer's last message. Send an approved template instead.

Your account requires recorded opt-in before this kind of message. Record the contact's consent first.

The number is on a suppression list for this kind of message (for example after a hard failure or a manual block).

The contact opted out of this kind of message. Do not send it again unless they opt back in.

WhatsApp limits how many marketing messages one person receives. Send later; with deferIfCapped the message waits automatically.

Your account's policy blocks this destination (a country or number range).

Messages to this country are not available for this account or message category.

The business has used its daily limit of new conversations. It resets on a rolling 24-hour basis and grows as quality stays high.

The chosen transport cannot carry this template category (for example a non-marketing template on the Marketing Messages API).

The message was held back by fraud and abuse checks. Contact support if you think this is wrong.

A number shared with the WhatsApp Business app cannot be deregistered from the API; disconnect it from the app side.

The WhatsApp Business Account already has the maximum number of phone numbers.

Connecting live numbers is not open yet on this platform. Use the sandbox until it is.

The data region you chose conflicts with the account's data residency policy. Pick an allowed region.

WhatsApp has blocked this Flow. Check its health in the console.

The resource changed or is in the wrong state for this action. Read it again and retry against its current state.

More than one region claims this account. Contact support with the requestId so ownership can be corrected; do not create another account or change regions to retry the operation.

The message has already been handed to WhatsApp, so it can no longer be canceled.

The message passed its validity period before it could be sent, so it was not sent.

This operation cannot be retried; check retryEligible on the operation before retrying.

The onboarding code has expired. Start the connection again to get a new one.

The WhatsApp Business Account is not connected to Toutye. Reconnect it in the console.

Someone else changed the conversation after you loaded it. Reload it and try again.

Another agent is replying in this conversation right now.

Take the conversation's reply claim before replying from an inbox.

Only published Flows can be sent. Publish the Flow first.

Data-exchange Flows need the sender's Flow encryption public key to be uploaded and verified.

The WhatsApp Business Account has not accepted the Marketing Messages API terms. Complete that step, or send through the Cloud API transport.

Detailed analytics are limited to the last 7 days right now. Ask for a shorter range.

WhatsApp had a temporary failure. Retrying is safe; queued messages are retried automatically.

WhatsApp refused the request for good. providerCode has Meta's reason; change the request before trying again.

WhatsApp did not say whether it accepted the message. Toutye does not resend it blindly; the final status arrives as an event, or the message is reported as unknown.

The WhatsApp connection's credential is no longer valid. Reconnect the WhatsApp Business Account.

WhatsApp has restricted the business account. The console shows the reason and any appeal path.

WhatsApp needs a payment method on the WhatsApp Business Account before it will send.

WhatsApp refused to register the phone number. Check the number and its verification code.

WhatsApp could not process the media file. Try another format or a smaller file.

WhatsApp blocked or throttled the Flow.

The Marketing Messages API refused the message; providerCode has the reason.

The number does not have WhatsApp or cannot receive messages. Do not retry.

WhatsApp is holding back marketing messages to this person as part of its own experiment. Nothing to fix.

WhatsApp rejected the template message, usually for wrong or missing parameters. Compare the parameters with the template.

The sender's display name is not approved by WhatsApp yet, so it cannot send.

A temporary failure inside Toutye, including load shedding under heavy demand (HTTP 503 with a Retry-After header and retryAfterSeconds; nothing was saved and no RateLimit headers are sent). Wait, then retry with the same Idempotency-Key.

Regional discovery is temporarily unavailable. Wait before retrying, or use your account's known regional API address. Keep the same Idempotency-Key when retrying a mutation.

Your account's regional API could not be reached. A mutation may already have been accepted: check its status and reuse the same Idempotency-Key when retrying. Do not send it to a different region.

An unexpected failure inside Toutye. Contact support with the requestId.

Toutye could not assemble the message (for example a template variable could not be filled). Nothing was sent.

Delivering an event to your endpoint failed. It is retried with backoff; see the webhook's delivery log.