From 3fcee305ecabd4cffada1e9298d7c63bb96e7085 Mon Sep 17 00:00:00 2001 From: Daniel Tolbert Date: Wed, 14 Feb 2018 13:40:31 -0500 Subject: [PATCH] updates to error code doc --- SUMMARY.md | 8 ++ codes.md | 246 +++++++++++++++++++++++++++++++++++++++++++++------ js/custom.js | 1 + 3 files changed, 229 insertions(+), 26 deletions(-) diff --git a/SUMMARY.md b/SUMMARY.md index 6bbb23d..4315f2a 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -58,6 +58,14 @@ ## Error Codes & Responses * [Message Error Codes](codes.md) + * [Message Error Reporting](codes.md#error-reporting) + * [Error Code Schema](codes.md#error-code-schema) + * [Error Code Table](codes.md#error-codes) + * [Bandwidth Detected Client Errors](codes.md#client-errors) + * [Carrier Reported Client Errors](codes.md#carrier-client) + * [Bandwidth Service Failures](codes.md#service-errors) + * [Carrier Reported Service Failures](codes.md#carrier-service-errors) + * [Carrier Errors with Ambiguous Cause](codes.md#carrier-ambiguous-errors) * [400 - Bad Request](errors/badRequest.md) * [401 - Unauthorized](errors/unauth.md) * [403 - Forbidden](errors/forbidden.md) diff --git a/codes.md b/codes.md index 5158f09..2000691 100644 --- a/codes.md +++ b/codes.md @@ -1,32 +1,204 @@ -# Message Delivery Code +# Bandwidth Messaging V2 API Error Reporting and Codes {#top} + +## Resources +* [Message Error Reporting](#error-reporting) +* [Error Code Schema](codes.md#error-code-schema) +* [Error Code Table](codes.md#error-codes) + * [Bandwidth Detected Client Errors](#client-errors) + * [Carrier Reported Client Errors](#carrier-client) + * [Bandwidth Service Failures](#service-errors) + * [Carrier Reported Service Failures](#carrier-service-errors) + * [Carrier Errors with Ambiguous Cause](#carrier-ambiguous-errors) + +## Error Reporting {#error-reporting} +The Bandwidth V2 messaging API presents errors on the [callback URL](events/messageEvents.md) using the [`message-failed`](events/messageFailed.md) type in the payload body along with an errorCode and description. An example is as follows: + +```json +[ + { + "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](#error-codes) should be used. + + +## Error Code Schema {#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. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+

Client / Server

+

Digit

+ 		+

Bandwidth / carrier

+

Digit

+ 		+

X

+ 		+

X

+
+

+

4

+ 		+

+

Client error

+ 		+

1

+ 		+

+

Bandwidth Rejected

+ 		+

+

Bandwidth Specific

+
+

3

+
+

4

+
+

7

+ 		+

Carrier Rejected

+ 		+

Carrier Normalized

+
+

5

+ 		+

Server Error

+ 		+

1

+ 		+

Bandwidth Server Error

+ 		+

Bandwidth Specific

+
+

2

+
+

5

+
+

6

+ 		+

Carrier Reported Service Failure

+ 		+

Carrier Normalized

+
+

9

+ 		+

Ambiguous Error

+ 		+

The error is related to downstream failures, but the specific reason for failure is unclear.

+
+ + +## Message Delivery Codes Table {#error-codes} + +### Bandwidth Detected Client Errors {#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. + +| Code | Description | +|:-----|:------------------------------------------------------------------------------| +| 4001 | Message was rejected for reasons other than those covered by other 4xxx codes | +| 4121 | Rejected as SPAM | +| 4301 | Malformed message encoding | +| 4302 | Malformed From number | +| 4303 | Malformed To Number | +| 4350 | Malformed message encoding | +| 4401 | Message is looping from carrier back to BW | +| 4403 | Messaging forbidden on From number | +| 4404 | Messaging forbidden on To number | +| 4405 | Unallocated from number | +| 4406 | Unallocated to number | +| 4410 | Could not download media | +| 4411 | Combined size of media too large | +| 4420 | No Route to Destination Carrier | +| 4421 | No Route to Destination Carrier | +| 4431 | Messaging on shortcode forbidden | +| 4432 | Messaging to country forbidden | +| 4433 | Messaging on Toll Free Number Forbidden | +| 4434 | Messaging to Toll Free Number Forbidden | +| 4451 | Invalid User Id | +| 4452 | Invalid Application Id | +| 4470 | Rejected as SPAM (future) | +| 4481 | From Number in black list | +| 4482 | To Number in black list | +| 4492 | Message to emergency number forbidden | +| 4493 | Unauthorized | + +### Carrier Reported Client Errors {#carrier-client} | Code | Description | |:-----|:------------------------------------------------| -| 4121 | Rejected as SPAM | -| 4301 | Malformed message encoding | -| 4302 | Malformed From number | -| 4303 | Malformed To Number | -| 4350 | Malformed message encoding | -| 4401 | Message is looping from carrier back to BW | -| 4403 | Messaging forbidden on From number | -| 4404 | Messaging forbidden on To number | -| 4405 | Unallocated from number | -| 4406 | Unallocated to number | -| 4410 | Could not download media | -| 4411 | Combined size of media too large | -| 4420 | No Route to Destination Carrier | -| 4421 | No Route to Destination Carrier | -| 4431 | Messaging on shortcode forbidden | -| 4432 | Messaging to country forbidden | -| 4433 | Messaging on Toll Free Number Forbidden | -| 4434 | Messaging to Toll Free Number Forbidden | -| 4451 | Invalid User Id | -| 4452 | Invalid Application Id | -| 4470 | Rejected as SPAM (future) | -| 4481 | From Number in black list | -| 4482 | To Number in black list | -| 4492 | Message to emergency number forbidden | -| 4493 | Unauthorized | | 4700 | Carrier Rejected as Invalid Service Type | | 4720 | Carrier Rejected as Invalid Destination Address | | 4740 | Carrier Rejected as Invalid Source Address | @@ -34,6 +206,14 @@ | 4751 | Message too long for carrier | | 4770 | Carrier Rejected as SPAM | | 4775 | Carrier Rejected due to user opt out | + +### Bandwidth Service Failures {#service-errors} + +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. + + +| Code | Description | +|:-----|:------------------------------------------------| | 5100 | Application Error | | 5101 | Application Error | | 5111 | Application Error | @@ -48,6 +228,11 @@ | 5500 | General Message Send Failure | | 5501 | General Message Send Failure | | 5503 | Service Unavailable | + +### Carrier Reported Service Failures {#carrier-service-errors} + +| Code | Description | +|:-----|:------------------------------------------------| | 5600 | Carrier Service Unavailable | | 5610 | Carrier Service Failure | | 5620 | Carrier Application Error | @@ -55,3 +240,12 @@ | 5650 | Carrier Service Failure | | 5999 | Unknown error from downstream | +### Carrier Errors with Ambiguous Cause {#carrier-ambiguous-errors} + +| Code | Description | +|:-----|:-----------------------------------------------------------------------------------------------------| +| 9902 | Timed out waiting for delivery receipt. The reason a delivery receipt was not received is not known. | +| 9999 | Unknown error from downstream. Carrier reported a failure code that is unknown to Bandwidth. | + + + diff --git a/js/custom.js b/js/custom.js index b9f86ee..17bdf20 100644 --- a/js/custom.js +++ b/js/custom.js @@ -27,6 +27,7 @@ module.exports = function ($) { 'uisetup.html', 'apisetup.html', 'numberOrderingSummary.html', + 'codes.html' ];