Error Codes

Overview

When an API request cannot be processed successfully, the response will contain an error code that identifies the reason for the failure.

Error codes provide a stable and machine-readable way to determine the cause of an error and implement appropriate error handling within your application.

The API provides endpoints that allow you to:

Retrieve information about a specific error code.
Retrieve the complete catalog of supported error codes.
Synchronize error code definitions for local caching.

Error Response Example

The following example shows a typical error response returned by the API:

{
  "code": 5000001
}

The code value uniquely identifies the error that occurred.

Common Error Handling Workflow

We recommend the following workflow when handling API errors:

Submit a request to the API.
Check whether the response contains an error code.
Look up the error code in your locally cached error code catalog.
Display a user-friendly message.
If the error code is not found locally, retrieve its details from the Error Codes endpoint.

Example Workflow

API Response

{
  "code": 5000001
}

Error Code Details

{
  "code": 5000001,
  "detail": "The server was unable to complete the request.",
  "status_code": InternalServerError
}

Error Code Reference

The table below contains all error codes currently supported by the API.

Code	Description	HTTP Status Code
4000001	The request payload that has have provided is incorrect.	BadRequest
4000002	The header X-Unique-Id is required and must match the regular expression ^[A-Za-z0-9-._]{10,36}$.	BadRequest
4000003	A username must be provided and must match the regular expression ^[a-zA-Z0-9_.]{8,30}$.	BadRequest
4000004	The client_key property must match the regular expression ^[A-Za-z0-9_]{3,35}$.	BadRequest
4000005	The client_id property must match the regular expression ^[A-Za-z0-9]{32}$.	BadRequest
4009900	The request body that has been submitted is incorrect.	BadRequest
4009901	The request parameters that has been submitted is incorrect.	BadRequest
4009999	A 4XX error occurred on the gateway while attempted to communicate with the intended resources.	BadRequest
4010001	Username and/or password provided are not correct or token is invalid.	Unauthorized
4010002	Unauthorized Api key.	Unauthorized
4019900	Not authorized to submit request.	Unauthorized
4030001	Forbidden to access requested resource.	Forbidden
4030002	Forbidden to complete request due to invalid/missing configuration.	Forbidden
4030003	Forbidden to complete request due to violation of operation rules.	Forbidden
4039900	Access is denied to submit request.	Forbidden
4039901	Bearer authentication token provided is expired.	Forbidden
4039902	The header X-Api-Key is required.	Forbidden
4039903	Signiture provided is invalid.	Forbidden
4039904	Bearer authentication token is required.	Forbidden
4039905	Request has been filtered by WAF.	Forbidden
4040001	Data attempted to be retrieved does not exist.	NotFound
4049900	The attempted requested resource does not exist.	NotFound
4090001	The header X-Unique-Id provided is not unique.	Conflict
4090002	The request with the same data has already been processed.	Conflict
4139900	Requested entity is too large.	RequestEntityTooLarge
4159900	Media type provided is not supported.	UnsupportedMediaType
4299900	The quota has been exceeded.	TooManyRequests
4299901	Too many requests have been submitted concurrently.	TooManyRequests
4220001	The given data is invalid.	UnprocessableEntity
4220002	Customer status must be in an active state for the request to complete.	UnprocessableEntity
4220003	Account status must be in an active state for the request to complete.	UnprocessableEntity
4220004	Card status must be in an active state for the request to complete.	UnprocessableEntity
4220005	Request could not be processed due to missing mandatory information.	UnprocessableEntity
4220006	Card provided is unassigned from a customer and cannot complete the requested request.	UnprocessableEntity
4220007	The request could not be processed due to server being unable to match the request signature against the request body.	UnprocessableEntity
4220008	Cards cannot be activated until they reach status 03 (Printing).	UnprocessableEntity
4224001	Customer details submitted have already been submitted for another customer.	UnprocessableEntity
4224002	The customer has already reached the maximum number of accounts that can be correlated to it.	UnprocessableEntity
4224003	The customer has already reached the maximum number of cards that can be correlated to it.	UnprocessableEntity
4224004	The customer does not have an active account available or an active account with sufficient funds to charge a fee.	UnprocessableEntity
4224005	The customer is on hold due to AML checks.	UnprocessableEntity
4224006	The customer is rejected due to AML checks.	UnprocessableEntity
4225024	The yearly maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225025	The monthly maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225026	The weekly maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225027	The daily maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225028	The hourly maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225029	The yearly maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225031	The account balance will exceed the limit configured.	UnprocessableEntity
4225032	The sum of the customer accounts balance will exceed the limit configured.	UnprocessableEntity
4225033	The lifetime maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225035	The monthly maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225036	The weekly maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225037	The daily maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225038	The hourly maximum number of transactions will exceed the limits configured.	UnprocessableEntity
4225053	The yearly maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225054	The monthly maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225055	The weekly maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225056	The daily maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225057	The hourly maximum amount of transactions will exceed the limit configured.	UnprocessableEntity
4225058	The yearly maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225059	The monthly maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225060	The weekly maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225061	The daily maximum number of transactions will exceed the limit configured.	UnprocessableEntity
4225062	The hourly maximum number of transactions will exceed the limits configured.	UnprocessableEntity
4225064	Account balance does not have sufficient funds to complete the request.	UnprocessableEntity
4225074	The transaction maximum amount will exceed the limit configured.	UnprocessableEntity
4225073	The transaction minimum amount has not reached the limit configured.	UnprocessableEntity
4245001	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245002	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245003	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245004	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245005	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245006	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245007	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245008	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245009	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245010	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
4245011	Request was not completed successfully due to a dependant component returned an unsuccessful response.	FailedDependency
5000001	The server was unable to complete the request.	InternalServerError
5009900	The server was unable to complete the request due to incorrect Api configurations.	InternalServerError
5009901	The server was unable to complete the request due to authorizer configuration error.	InternalServerError
5009902	The server was unable to complete the request due to authorizer failure.	InternalServerError
5009999	A 5XX error occurred on the gateway while attempted to communicate with the intended resources.	InternalServerError
5030001	Service is unavailable due to undergoing maintenance.	ServiceUnavailable
5049900	The gateway timed out while attempted to communicate with the intended resources.	GatewayTimeout
5049901	The gateway timed out while waiting for a response from the intended resources.	GatewayTimeout

Retrieve a Specific Error Code

Use the following endpoint to retrieve detailed information about a specific error code.

Endpoint

GET /errorcodes/{code}

Documentation

https://api-docs.msledge.tech/#tag/ErrorCodes/paths/~1errorcodes~1%7Bcode%7D/get

Example Request

curl -X GET \
  'https://api.msledge.tech/errorcodes/5000001' \
  -H 'accept: application/json' \
  -H 'X-Unique-Id: a..z' \
  -H 'X-Api-Key: a..z' \
  -H 'Authorization: Bearer a..z'

Example Response

{
  "code": 5000001,
  "detail": "The server was unable to complete the request.",
  "status_code": InternalServerError
}

Retrieve All Error Codes

Use the following endpoint to retrieve the complete catalog of supported error codes.

Endpoint

GET /errorcodes

Documentation

https://api-docs.msledge.tech/#tag/ErrorCodes/paths/~1errorcodes/get

Example Request

curl -X GET \
  'https://api.msledge.tech/errorcodes' \
  -H 'accept: application/json' \
  -H 'X-Unique-Id: a..z' \
  -H 'X-Api-Key: a..z' \
  -H 'Authorization: Bearer a..z'

Example Response

[
  {
    "code": 4000001,
    "detail": "The request payload that has have provided is incorrect.",
    "status_code": "BadRequest"
  },
  .
  .
  .
  {
    "code": 5000001,
    "detail": "The server was unable to complete the request.",
    "status_code": InternalServerError
  }
]

The response contains a collection of all supported error codes and their associated descriptions.

Best Practices

Cache Error Codes Locally

To improve performance and reduce unnecessary API requests, applications should maintain a local cache of the error code catalog.

Recommended approach:

Retrieve the complete error code catalog from the /errorcodes endpoint.
Store the catalog in memory or a local database.
Refresh the catalog periodically.
Resolve error codes locally whenever possible.

Refresh Frequency

Error code definitions are updated infrequently, typically only a few times per month.

For most integrations, refreshing the error code catalog once every 24 hours is sufficient.

Fallback Strategy

If an error code is not found in the local cache:

Retrieve the error details using the /errorcodes/{code} endpoint.
Update the local cache.
Continue processing using the retrieved information.

This strategy minimizes network overhead while ensuring your application remains synchronized with the latest error code definitions.

Error Codes

Overview​

Error Response Example​

Common Error Handling Workflow​

Example Workflow​

Error Code Reference​

Retrieve a Specific Error Code​

Retrieve All Error Codes​

Best Practices​