Troubleshooting Error Codes

The errors you may encounter while using the Phone.com REST API can be categorized as one of the following:


Problems Making REST Requests

Most of your interactions with the API will be sending HTTP requests. These requests can fail, due to a number of issues:

  • A connectivity problem
  • A problem with the syntax of the HTTP request
  • A problem with the syntax of the body of the request—that is, with the JSON document you are sending with your API request
  • Sending a command that is syntactically correct but not logically valid—for example, if you were to reference a non-existent resource or try to delete a resource that is in use.

Once you have ruled out connectivity issues and are receiving HTTP responses back from our API server when you send a request, the Phone.com API will provide you with standard HTTP error codes that should indicate what is causing your request to fail.

Troubleshooting Standard HTTP Error Codes

  • 400 Invalid Request: Points to a problem with the syntax of the request
  • 401 Unauthorized: Indicates a problem with authentication
  • 403 Forbidden: Suggests a permissions problem (check the `resource ID`_ of the resource you are targeting)
  • 404 Not Found: Indicates that you requested a resource that does not exist (for example, a resource name or resource ID)
  • 409 Conflict: Indicates that you have made a valid request that is syntactically correct but that cannot be performed for some reason
  • 500 Internal Server Error: Points to an error with our servers, of which we will likely be aware. If the issue persists, please contact Phone.com API Support.
  • 504 Gateway Timeout: We encountered a timeout while processing your request. If the issue persists, please contact Phone.com API Support.

Reviewing Extended Error Codes

Each Phone.com API error message includes an extended error code in the reply. These codes are found in a JSON document that you can read or parse using a client app to further diagnose what is causing the error.

Extended-error documents have the following format:


 {
    "error": {
        "code": 10004
        "info": "Invalid credentials. Please check application key and password",
        "url": "https://docs.phone.com/refguides/errorref/generalerrors.html#error-code-10004",
    }
  }

Note that the error code field contains a unique code that will stay constant—that is, the same error will always result in the same extended error code. The error info field is a short description of the error that indicates the specific problem. This description may change over time, so please avoid parsing these fields directly. Finally, the error url field contains a link to a detailed description of the error should you need more information.

When applicable, an extended error code can contain details about the JSON data that triggered the error. Details are listed in an array under the detail field.

Example:


 {
     "error": {
         "code": 30005,
         "info": "Invalid request. The resource is in use.",
         "url": "https://docs.phone.com/errors/#30005",
         "detail": [
             "the name: test is in use in another route."
         ]
     }
 }

Call-control Script Issues

When making a POST request to control a phone call, the JSON document sent in the request is a list of instructions for handling the call.

The list of commands could be syntactically correct but logically incorrect. For example, you could be trying to play a greeting before the phone call is connected, trying to send a command after the call has ended, or sending commands while the system is processing a previous command.

In these cases, the system will reply to the HTTP request with an HTTP 400 error code and an extended error code describing the problem.

It is also possible for the execution of your script to be interrupted, resulting in an error even though your request was valid when it was received. For example, the call recipient might hang up while commands are pending execution. In this case, our system will abort the script execution and either return an HTTP response to you (if the HTTP request is synchronous) or send an HTTP event to your application URL (if the request is asynchronous). In both cases, the HTTP response will incidate the success or failure of each command.

Also note that when controling a phone call, our API expects the next command within 60 seconds after completing the current set of commands. If your application does not provide the next set of commands, the call will be ended by the API and subsequent commands will fail.

Missing Events

Another category of errors you may encounter with the Phone.com API is missing events sent to your webserver using HTTP.

HTTP events are used to notify your application of phone-call-related events, including:

  • New incoming calls
  • Expected events, such as DTMF input received or a set of commands being completed
  • Unexpected events, such as a call hang-up while commands are still being processed
  • Incoming SMS messages

Events like this are sent as HTTP requests to the URLs defined for your application in your Phone.com API Developer account settings. If your HTTP server is unavailable or returns any response other than 200 Success errors, our API will try sending the event to your backup URL, if configured.

If you are not receiving HTTP requests from our API in this situation, please check the following:

  • Make sure that the correct URL is defined for your application in your account settings. Note that our API supports sending the event over HTTP or HTTPS.
  • Make sure that you are not using a self-signed certificate when using HTTPS.
  • Check that your webserver can be reached on the Internet.
  • Check your webserver’s log.

Learn More: