Errors

When a request doesn't work, the API tells you in two ways: the HTTP status code and the status field in the response body. This page explains both, lists the errors you're most likely to see, and tells you what to do about each one.

Always check the `status` field

Every response from the API includes a status field:

"status": true means the request worked.

"status": false means it didn't, and the error field explains why.

WARNING

Don't rely on the HTTP status code alone. Many errors, such as a missing field in your request or an unknown web address, come back with HTTP status 200, which normally means success. Always check status in the response body to know whether your request worked.

What an error looks like

Most errors look like this:

{
  "status": false,
  "error": {
    "code": 9001,
    "message": "Invalid body!"
  }
}

Field	What it means
`status`	Always `false` for an error.
`error.code`	A number that identifies the error. Use it in your code to decide what to do.
`error.message`	A short explanation you can read, log, or show to your team.

A few errors look slightly different:

Some errors have only a message. error is plain text instead of an object with code and message, for example "error": "Limit must be greater than 0".

The "no API key" error uses statusCode instead of code.

If the request body isn't valid JSON, the API returns a short HTML page saying Bad Request with HTTP status 400, instead of JSON.

TIP

If your code reads error.code, also handle the case where error is plain text, so an unexpected error doesn't break your software.

HTTP status codes

Status	Meaning	When you'll see it
`200`	OK	The request reached Chronox. Check `status`: it can still be an error.
`400`	Bad Request	The request body isn't valid JSON, or a value in the address (such as `limit` or `offset`) is out of range.
`401`	Unauthorized	The API key is missing, wrong, deleted or expired.
`403`	Forbidden	The endpoint isn't available through the API, or your account is inactive.
`429`	Too Many Requests	You've gone over the rate limit. See Rate limiting.
`500`	Internal Server Error	Something went wrong on Chronox's side.

Common errors

Key and account errors

Code	Message	What to do
`-999`	ERROR! Invalid authentication found.	Add your API key in the `Authorization` header. See Authentication.
`9243`	Invalid or expired API key	Check you copied the full key. If it's been deleted or has expired, create a new one.
`9020`	ERROR! Access not granted.	This endpoint isn't available through the API. Use only the endpoints listed in the sidebar.
`9248`	Your account is inactive. Please contact support.	Contact Chronox support.
`9246`	Your organization is paused by admin. Please contact your admin.	Messages can't be sent while your workspace is paused. Contact your workspace admin.
`9999`	API key rate limit exceeded. Please try again later.	Wait for the number of seconds in `retry_after_seconds`, then try again.

Request errors

Code	Message	What to do
`-999`	Error Invalid API Request.	The web address doesn't match any endpoint. Check it for typos. Note that this comes back with HTTP status `200`.
`9001`	Invalid body!	Something in your request body is missing or wrong. Compare your request with the example on the endpoint's page.
`9002`	ERROR! Invalid query parameter.	A value in the web address (after the `?`) is missing or wrong.
`9112`	ERROR! Invalid params.	A value inside the web address path is missing or wrong, such as an ID.
`9032`	Data not found.	Something you referred to, such as an ID, doesn't exist in your account.

NOTE

Validation errors return one message for the whole request. They don't list every field that's wrong. If you get Invalid body!, check each field against the endpoint's page.

WhatsApp template errors

These come from Create Whatsapp Template and Send Whatsapp Template.

Code	Message	What to do
`9437`	Template name already exists.	Choose a different template name.
`9147`	ERROR! The WhatsApp template is not available for use.	The template isn't approved yet, or it's been paused or rejected by Meta. Check it with Get Whatsapp Template Details.
`9316`	Marketing template body can contain a maximum of 10 emojis.	Remove some emojis.
`9317`	Utility template body cannot have more than 2 consecutive line breaks.	Remove the extra blank lines.
`9319`	Marketing template body cannot have more than 2 consecutive line breaks.	Remove the extra blank lines.
`9318`	Carousel template body cannot have more than 1 consecutive line break.	Remove the extra blank lines.
`9248`	This template contains variable parameters with incorrect formatting. …	Write blanks in lowercase letters, numbers and underscores inside double curly brackets, for example `{{customer_name}}`.
`9307`	Footer is required when code expiration minutes is set …	For authentication templates with an expiry time, add a footer.

INFO

Code 9248 is currently used for two different errors: an inactive account and a badly formatted template variable. Check the message as well as the code to tell them apart.

If Meta itself refuses a new template, the error contains Meta's code and message, for example:

{
  "status": false,
  "error": {
    "code": "…Meta's error code…",
    "message": "…Meta's reason…"
  }
}

These rules are set by Meta, not Chronox. The message explains what Meta didn't accept.

Conversation errors

Code	Message	What to do
`9145`	WA thread meta data not found	Chronox couldn't find the customer's WhatsApp details for this conversation. Check the conversation or phone number you sent.
`9247`	Error: The thread has been deleted or no longer exists.	The conversation has been deleted.

Server errors

Code	Message	What to do
`9000`	Something went wrong with the server.	Wait a moment and try again.
`9028`	Server error occurred while executing Database query.	Wait a moment and try again. If it keeps happening, contact Chronox support.

When a message isn't sent

Sending messages works slightly differently. Chronox passes your message to WhatsApp, and WhatsApp can refuse it even when your request is correct. When this happens, the response still says "status": true, because Chronox handled your request successfully. You need to look inside data to see whether WhatsApp accepted the message.

Send Whatsapp Message

Send Whatsapp Template

Check data.wa_message_response.status. If it's false, WhatsApp didn't accept the message. WhatsApp's reason is in data.wa_message_response.error.response.data.error.message.

{
  "status": true,
  "data": {
    "wa_message_response": {
      "status": false,
      "error": {
        "response": {
          "data": {
            "error": {
              "message": "…WhatsApp's reason…",
              "code": "…WhatsApp's error code…"
            }
          }
        }
      }
    }
  }
}

The real response contains more fields than shown here.

NOTE

Even when WhatsApp accepts a message, it can still fail to deliver it later. Those later failures don't appear in the send response.

Should you try again?

Situation	Try again?
`429` rate limit	Yes, after waiting `retry_after_seconds`.
Server errors (`500`, `9000`, `9028`) on requests that only read data	Yes, after a short wait. Wait longer between each attempt.
Server errors when sending a message or creating a template	Check first. The first attempt may have worked. Look at the conversation with Get Thread Details, or at your templates with Get Whatsapp Templates, before sending again.
`401`, `403`, and errors about your request (`9001`, `9002`, `9112`, template errors)	No. Sending the same request again will give the same error. Fix the problem first.

WARNING

Sending the same message twice will deliver it to the customer twice. The API has no built-in protection against duplicates, so if you're unsure whether a message was sent, check before trying again.

INFO

For some short-lived WhatsApp problems, Chronox automatically tries sending your message one more time before responding. You don't need to do anything for this.

What this page doesn't cover

Rate limit details. See Rate limiting.

API key problems in depth. See Authentication.

Every possible message. This page lists the errors you're most likely to see. Other errors follow the same format, and their message explains the problem.

Always check the status field#

What an error looks like#

HTTP status codes#

Common errors#

Key and account errors#

Request errors#

WhatsApp template errors#

Conversation errors#

Server errors#

When a message isn't sent#

Should you try again?#

What this page doesn't cover#