Error Codes

Error Codes AI Tools

Open in ChatGPT

Open in ChatGPT to ask questions about this page

Open in Claude

Open in Claude to ask questions about this page

Copy as Markdown

Copy this page as markdown to use with AI assistants

View as Markdown

Open this page as markdown in a new tab

Arattai utilises HTTP status codes to convey the success or failure of an API call. Status codes in the 2xx range signify success, while 4xx codes indicate client-side errors due to invalid or missing request information. Conversely, 5xx codes point to server-side errors.

The table below covers error codes specific to the Business-Initiated Messaging APIs - Promotional, Transactional, and Authentication messages.

Endpoint Status Reason Sample Error Response
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 The specified phone number is not registered with Arattai.
{
  "message": "The recipient is not an Arattai user.",
  "code": "invalid_recipient"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 Invalid input provided in the request.

Variables parameter type mismatch:

{
  "message": "Mismatch in accepted data type for 'variables' parameter.",
  "code": "input_json_invalid"
}

Authentication button present but code not sent:

{
  "message": "The parameter 'authentication_code' is missing.",
  "code": "param_missing"
}
/api/v1/transactions 400 File/attachment error (transactions only).

File is required but missing:

{
  "message": "The parameter 'files' is missing.",
  "code": "param_missing"
}

File type does not match the required type:

{
  "message": "Invalid file type. Expected file type $type.",
  "code": "invalid_file_type"
}

File parameter sent but not expected by template:

{
  "message": "'files' is an extra key in the Object.",
  "code": "extra_key_found"
}

File size exceeds the allowed limit:

{
  "message": "Maximum allowed file size has been exceeded.",
  "code": "file_maxsize_exceeded"
}
/api/v1/promotions 400 User has unsubscribed from promotional messages.
{
  "code": "user_unsubscribed_promotions",
  "message": "User has unsubscribed from promotional messages."
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 Malformed field, or Arattai rejected the payload.
{
  "code": "invalid_input",
  "message": "Either the input stream or parameter is invalid or absent"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 Arattai-BusinessNumberId (or another required header) is absent.
{
  "code": "missing_header",
  "message": "Arattai-BusinessNumberId header is required"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 The rate limit has been exceeded. Returned as 400, not 429 - match on the code, not the status.
{
  "code": "too_many_requests",
  "message": "You have reached the maximum number of requests"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 401 The OAuth token is missing, invalid, or expired.
{
  "code": "invalid_oauthtoken",
  "message": "You are not authenticated to do this operation"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 401 The request was not authenticated.
{
  "code": "unauthenticated",
  "message": "The request was not authenticated"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 403 The token lacks the required scope, or the request crosses a company/tenant boundary.
{
  "code": "unauthorised",
  "message": "The user does not have enough permission to access the resource"
}
/api/v1/promotions 403 Promotional messaging is switched off for this business number. Rejected before the send is attempted or billed.
{
  "code": "promotions_disabled",
  "message": "Promotional messaging is disabled for this business number"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 405 The HTTP method used is not supported for this endpoint.
{
  "code": "invalid_method",
  "message": "Invalid method"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 409 The supplied user_id no longer matches the recipient phone number's current Arattai user. See Recipient Identity Check.
{
  "code": "recipient_identity_mismatch",
  "message": "The provided user_id does not match the current Arattai user for this phone number. The number may now belong to a different user"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 A media/link URL in the payload isn't reachable.
{
  "code": "url_not_accessible",
  "message": "The media URL provided is not accessible"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 402 Insufficient credits to send. Production endpoints only - test sends aren't credit-gated.
{
  "code": "payment_required",
  "message": "Insufficient credits to perform this action"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 A send carrying user_id found no ongoing conversation with that recipient. Send by phone_number alone to reach a recipient you haven't conversed with.
{
  "code": "no_ongoing_conversation",
  "message": "No ongoing conversation exists with this user_id. Send by phone_number instead"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 This business number is not permitted to message the recipient.
{
  "code": "business_recipient_not_allowed",
  "message": "This business number is not allowed to message the recipient"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 400 The template ID is not associated with this business.
{
  "code": "unassociated_template",
  "message": "The template ID is not associated with this business"
}
/api/v1/promotions /api/v1/transactions /api/v1/authentications 500 An unexpected server error occurred.
{
  "code": "operation_failed",
  "message": "An unexpected error occurred while processing the request"
}
/api/v1/promotions/test /api/v1/transactions/test /api/v1/authentications/test 429 The test customer's 500/day message cap has been reached. /test endpoints only.
{
  "code": "test_customer_message_limit_exceeded",
  "message": "This test customer has reached its daily message limit. Please try again later"
}
/api/v1/transactions 400 File extension not in the allowed set. /transactions and /transactions/test only, when a files attachment is included.
{
  "code": "unsupported_file",
  "message": "File is not supported"
}
/api/v1/transactions 400 File content-type not allowed, or mismatched with its extension.
{
  "code": "invalid_file_type",
  "message": "The uploaded file type is not supported"
}
/api/v1/transactions 400 File name is invalid or contains unsafe characters.
{
  "code": "invalid_file_name",
  "message": "File name is invalid"
}
/api/v1/transactions 400 The uploaded file was flagged by the antivirus scan.
{
  "code": "antivirus_threat",
  "message": "The uploaded file was flagged by the antivirus scan"
}
/api/v1/transactions 400 The uploaded file is zero bytes.
{
  "code": "empty_file_not_allowed",
  "message": "The uploaded file is empty"
}
/api/v1/transactions 413 File (or total request) exceeds the size limit for its media type.
{
  "code": "file_size_too_large",
  "message": "Size of the file is too large"
}