Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Mistakes happen, and mostly they will be yours, not ours. Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

Before reaching out to support with an error, please be aware that 99% of all reported errors are, in fact, user errors. Therefore, please carefully check your code before contacting SenGo support.

Status codes

Here is a list of the different categories of status codes returned by the SenGo API. Use these to understand if a request was successful.

Name
2xx
Description
A 2xx status code indicates a successful response.
Name
4xx
Description
A 4xx status code indicates a client error — this means it's a you problem.
Name
5xx
Description
A 5xx status code indicates a server error — you won't be seeing these.

Error types

Whenever a request is unsuccessful, the SenGo API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

Here is a list of the two error types supported by the Protocol API — use these to understand what you have done wrong.

Http Code	Error Code	Message
400	CREATE_FAILED	We encountered an error while creating your request from our switching service, please try again!
401	UNAUTHORIZED	Authorization failed. Please provide valid credentials.
401	PRODUCT_ACCESS_ERROR
402	INSUFFICIENT_BALANCE	Insufficient balance. Unable to perform the transaction.
403	UNAUTHORIZED	The API request is not permitted from your current location or IP address.
403	PAYMENT_INACTIVE_ERROR
404	TRANSACTION_NOT_FOUND	The requested transaction could not be found.
429	PAYMENT_INTERNAL_ERROR
409	DUPLICATE_REFERENCE
422	REQUEST_INVALID	The request is invalid or contains invalid parameters.
422	INVALID_SIGNHASH	The provided sign hash is invalid or does not match the expected value.
429	TOO_MANY_REQUEST	The maximum number of requests has been exceeded. Please try again later.
500	PRODUCT_INTERNAL_ERROR	The upstream connection has been terminated due to connection timeout from bank aggregator.
501	PRODUCT_UNSUPPORTED
503	RUN_OUT_UPSTREAM_CONNECTION	The upstream connection has been terminated due to connection timeout from bank aggregator.
503	PRODUCT_UNDER_MAINTENANCE
504	UPSTREAM_TIMEOUT_CONNECTION	The connection to the upstream server timed out.

Error response

{
    "responseCode": "UNAUTHORIZED",
    "responseMessage": "Authorization failed. Please provide valid credentials."
}