Skip to main content
Most errors from the TGO Business API fall into a small set of categories: sender number issues, account verification gaps, API key configuration problems, and recipient reachability. Understanding what each error means and how to resolve it will help you get back to sending quickly.
Always call GET /api/v1/contacts/lookup before sending a message to verify that the recipient exists and can receive messages. This prevents failed sends before they happen.

​
Common errors

Error response:
{
  "message": "The sender number is not active."
}
What it means: The sender number you specified is not in a state that allows sending. It may be pending OTP confirmation, rejected, or suspended.How to resolve:
  1. List your sender numbers and check the status field for the number you are using.
  2. If the status is pending_verification, the OTP has not been entered yet. Ask the number owner to complete OTP verification in the TGO Business dashboard.
  3. If the status is rejected, the number cannot be used. Register a different sender number.
  4. If the status is suspended, contact your account administrator.
Error response:
يجب أن يكون صاحب الرقم موثقًا داخل TGO Connect قبل استخدام API الإرسال.
(Translation: The number owner must be verified inside TGO Connect before using the sending API.)What it means: The sender number’s OTP verification is complete, but the TGO Connect account linked to this number has not been verified. These are two separate requirements — passing OTP ownership confirmation is not enough.How to resolve:The number owner must verify their TGO Connect account independently. No new OTP is needed, and no action is required on the TGO Business side. Once verification is complete, the sender number becomes ready automatically.See Account Verification for a detailed explanation of both steps.
What happens: The API returns a 403 Forbidden or permission-related error when you attempt an operation your key is not authorized for.What it means: Your API key does not have the required scope for the endpoint you are calling. Each operation requires a specific scope:
OperationRequired scope
Send messagesmessages.send
Read message logsmessages.read
Look up contactscontacts.lookup
Read usage datausage.read
How to resolve:
  1. In the TGO Business dashboard, navigate to your API key settings.
  2. Check which scopes are assigned to the key you are using.
  3. Either add the required scope to the existing key, or create a new key with the correct scope (or scope: * for full access).
  4. Update your integration to use the new key if you created a replacement.
What happens: Your message request fails or the message is not delivered because the recipient’s phone number is not reachable through TGO Connect.What it means: The recipient either does not have a TGO Connect account, has not verified their phone number, or is otherwise not reachable.How to resolve:Use the contact lookup endpoint before sending to check whether the recipient can receive messages:
curl "https://{tenant-domain}/api/v1/contacts/lookup?phone=+201010000000" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: application/json"
Check the response fields:
  • exists: whether the phone number is registered in TGO Connect
  • can_receive: whether the number can receive messages
  • reason_code: "ok" if reachable; other values indicate why sending would fail
Only send the message if can_receive is true. This endpoint requires the contacts.lookup scope.
What happens: The API returns 401 Unauthorized for any request.What it means: The API key in your request is missing, incorrect, or has been revoked.How to resolve:
  1. Confirm you are passing the key in the X-Api-Key header.
  2. Check that the key value is copied correctly with no extra spaces or characters.
  3. In the TGO Business dashboard, verify that the key has not been revoked or deleted.
  4. If the key is no longer valid, generate a new one and update your integration.

​
HTTP status code reference

Status codeMeaning
401 UnauthorizedAPI key is missing, invalid, or revoked.
403 ForbiddenAPI key lacks the required scope for this operation.
422 Unprocessable EntityRequest body is invalid. Check required fields and field values.
204 No ContentOperation succeeded with no response body (e.g., revoking a resource).