API and Widget Errors

On this page you will find the different errors our API and Widget can return, alongside with the http statuses. These include controlled and uncontrolled errors.

At Vumi, we work hard to ensure a smooth experience with our app by rigorously testing to minimize errors. However, we know that sometimes issues are unavoidable. We have created this guide to help you handle them adequately when they occur.

Response Codes

Status CodeDescription


Success - The requested action was performed succesfully


Bad request - The request returned an error, typically due to missing or incorrect information.


Unauthorized - Credentials are missing or invalid. This typically means you need to refresh the session.


Forbidden - You are not allowed to perform the requested action.


Not Found - The resource you are trying to access could not be found based on the information you provided.


Internal Server Error - An uncontrolled error has occurred.

How to respond to different errors

Status code 5xx

5xx status code indicate server-side errors. These types of errors are typically temporary and may resolve themselves without intervention. For that reason, we recommend you implement a retry logic with incremental delays for 3-5 times before reporting the error to us. A common approach, and the one we do reccommend, is the exponential backoff with jitter, which adds randomness to the delay to prevent synchronized retries from multiple clients.

Status code 4xx

4xx status codes are controlled errors from our systems. These typically mean your request was either lacking important information or the information you provided is incorrect. For that reason, when you encounter these type of status codes you should not retry the same request.

Last updated