747 SMS API

Error Handling

Learn about error responses and how to handle them in your applications.

The 747 SMS API uses standard HTTP status codes and returns detailed error information in the response body. Understanding these errors will help you troubleshoot issues and improve your application's reliability.

Error Response Format

All error responses follow a consistent format:

{
  "error": {
    "code": "error_code",
    "message": "A human-readable error message",
    "details": {
      // Additional error details when available
    }
  }
}

HTTP Status Codes

The API uses the following HTTP status codes:

Status CodeDescription
200 OKThe request was successful
201 CreatedA new resource was successfully created
400 Bad RequestThe request was invalid or malformed
401 UnauthorizedAuthentication failed or was not provided
403 ForbiddenThe authenticated user doesn't have permission
404 Not FoundThe requested resource doesn't exist
422 Unprocessable EntityThe request was well-formed but had semantic errors
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorAn error occurred on the server

Common Error Codes

Here are some common error codes you might encounter:

Error CodeDescription
invalid_requestThe request is missing required parameters or has invalid parameters
authentication_failedAuthentication credentials are invalid
insufficient_fundsAccount balance is too low to complete the request
invalid_phone_numberThe provided phone number is invalid or in an unsupported format
message_too_longThe message exceeds the maximum allowed length
rate_limit_exceededYou've exceeded the rate limit for API requests
resource_not_foundThe requested resource (message, account, etc.) doesn't exist

Error Examples

Invalid Phone Number

// HTTP Status: 400 Bad Request
{
  "error": {
    "code": "invalid_phone_number",
    "message": "The phone number '+1555123' is invalid. Phone numbers must be in E.164 format.",
    "details": {
      "parameter": "to"
    }
  }
}

Authentication Failed

// HTTP Status: 401 Unauthorized
{
  "error": {
    "code": "authentication_failed",
    "message": "Invalid or expired access token",
    "details": {
      "hint": "Generate a new access token"
    }
  }
}

Rate Limit Exceeded

// HTTP Status: 429 Too Many Requests
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later.",
    "details": {
      "rate_limit": {
        "limit": 100,
        "remaining": 0,
        "reset_at": "2023-03-25T12:00:00Z"
      }
    }
  }
}