Errors

Every response from the Alaaqat API carries an HTTP status code. An integration that reads it can tell a request worth sending again from one that will fail the same way every time, and can show the right message to the person who has to fix it: a wrong key, a missing permission, a full plan or a bad value.

This page lists the codes the API answers with and what each one means here. Each endpoint page lists the ones that endpoint can return.

Send JSON, ask for JSON

Send Accept: application/json with every request, and Content-Type: application/json with every request that has a body. Without the Accept header, a refused request can come back as a redirect or a web page instead of the JSON error described here.

Successful responses

Status Meaning
200 OK The request worked.
201 Created A record was created. It is under data.
206 Partial Content A list worked, and more pages follow. Read the next one from links.next, see Pagination.

Treat 206 as a success. It is not an error, only a sign that the list goes on.

The shape of an error

An error answers with a JSON object whose message says what went wrong:

{
    "message": "Unauthenticated."
}

A 422 also carries errors, with one entry for each field that failed and the reasons it failed:

{
    "message": "The title field is required. (and 1 more error)",
    "errors": {
        "title": [
            "The title field is required."
        ],
        "items.0.quantity": [
            "The items.0.quantity field is required."
        ]
    }
}

The messages are written for developers. They can change, so decide what to do from the status code and the field names, not from the wording.

Status codes

Status Meaning What to do
400 The request is valid, but it can't be carried out as sent. For example, the contact has no value for a property a template variable uses, or WhatsApp refused the message. The message says why. Fix the cause the message names, then send again.
401 The API key is missing, wrong, expired or revoked. Check the Authorization header, or create a new key. See Authentication.
402 A limit of your plan is reached, such as the number of custom properties, notes or canned responses, or the account has run out of credits the request needs, such as verification code credits. Free some room, buy credits or move to a bigger plan. See the plans on the pricing page.
403 The key doesn't carry the ability the endpoint needs, the team member who created the key lacks the permission for the action, or the action isn't allowed on this record, for example a record they can't see or a property Alaaqat maintains. The message tells the cases apart. Add the ability to the key, or ask an admin for the permission. See Permissions & Abilities.
404 The record doesn't exist in your account, or the endpoint isn't open to API keys. Check the _id and the URL. Only the endpoints in this reference accept API keys.
422 A field failed validation. errors names each field. Correct the fields, then send again.
423 The team member who created the key is disabled in the account, or the account is scheduled for deletion. Ask an admin to activate the team member again, or to cancel the deletion.
429 Too many requests. Either the account's rate limit is reached, see Overview, or an endpoint's own limit, such as the wait between two verification codes to the same number. Wait, then send again. When the response has a Retry-After header, it gives the number of seconds to wait.
500 Something went wrong on our side. Send again a little later. If it keeps failing, contact support with the time of the request.

What to retry

Send a request again unchanged only after a 429 or a 500:

  • After a 429, wait the number of seconds in the Retry-After header, or a minute when it has none.
  • After a 500, wait a little longer before each new try, and stop after a few tries.

Every other error fails the same way until something changes: the request, the key, the team member's permissions or the plan. Sending it again in a loop only uses up your rate limit.

{warning} Before you send a create request again after a 500, list the records to check that the first one wasn't created. Otherwise you may end up with the record twice.