Bandwidth Messaging V2 API Error Reporting and Codes

Resources

• Message Error Reporting
• Error Code Schema
• Error Code Table
  • Bandwidth Detected Client Errors
  • Carrier Reported Client Errors
  • Bandwidth Service Failures
  • Carrier Reported Service Failures
  • Carrier Errors with Ambiguous Cause

Error Reporting

The Bandwidth V2 messaging API presents errors on the callback URL using the message-failed type in the payload body along with an errorCode and description. An example is as follows:

[
  {
    "type"          : "message-failed",
    "time"          : "2016-09-14T18:20:16Z",
    "description"   : "forbidden to country",
    "errorCode"     : 4432,
    "to"            : "+52345678903",
    "message"       : {
    "id"            : "14762070468292kw2fuqty55yp2b2",
    "time"          : "2016-09-14T18:20:16Z",
    "to"            : [
        "+12345678902",
        "+52345678903"
      ],
    "from"          : "+12345678901",
    "text"          : "Hey, check this out!",
    "applicationId" : "93de2206-9669-4e07-948d-329f4b722ee2",
    "media"         : [
      "https://s3.amazonaws.com/bw-v2-api/demo.jpg"
      ],
    "owner"         : "+12345678901",
    "direction"     : "out"
    }
  }
]

The description is purely informative and should not be utilized in error handling routines. Only the errorCode should be used.

Error Code Schema

Bandwidth’s error code schema for messaging V2 is comprised of a 4 digit code. As shown in the table below, the most significant digit indicates whether the error is client (customer) or server in nature while the second most significant indicates whether the error was reported by Bandwidth or the downstream carrier. The last 2 are Bandwidth specific codes or bandwidth normalization of carrier specific codes.

Message Delivery Codes Table

Error Types

• Bandwidth Detected Client Errors
• Carrier Reported Client Errors
• Bandwidth Service Failures
• Carrier Reported Service Failures
• Carrier Errors with Ambiguous Cause

Bandwidth Detected Client Errors

A 4xx code indicates that Bandwidth or the downstream carrier has identified some element of the message request unacceptable. Repeating the request will produce the same result.

Carrier Reported Client Errors

Bandwidth Service Failures

A 5xx code indicates that either Bandwidth or the downstream carrier has reported a service failure. For Bandwidth failures, the customer can retry the request and expect a different result. For carrier errors a retry may also yield a different result however the customer should limit to a single retry attempt as the error encoding schema and strategy varies greatly by carrier and while Bandwidth endeavors to normalize carrier codes into predictable values there can be exceptions.

Carrier Reported Service Failures

Carrier Errors with Ambiguous Cause