Our API uses standard HTTP status codes to indicate the success or failure of a request. This guide will help you understand the types of errors you might encounter and how to resolve them.

HTTP Status Codes

Code	Meaning	Description
200	OK	Request was successful. Check the response data for further details.
201	Created	A new resource was successfully created.
400	Bad Request	Your request is invalid. Check for missing fields, wrong data types, etc.
401	Unauthorized	Missing or invalid API key. Check your credentials.
403	Forbidden	You do not have permission to access the requested resource.
404	Not Found	The endpoint or resource you're trying to reach doesn’t exist.
429	Too Many Requests	You’ve hit the rate limit. Please slow down your requests.
5xx	Server Error	Something went wrong on our end. Try again or contact support.

Authentication & Authorization Errors

Occurs when your API key is missing, expired, or incorrect.

ℹ️
Ensure the key you are using matches the request, requests that requires encryption is authenticated with the Public key while other requests are authenticated by the secret key.

{
    "status": "failed",
    "statusCode": "401",
    "message": "Invalid SECRET key. Please check and try again"
}

☑️
Fix
Add the correct Authorization header:
Authorization: Bearer YOUR_SECRET_KEY

Encryption Errors

Occurs when the payload has not been properly encrypted.

{
    "status": "failed",
    "statusCode": "400",
    "message": "Unable to find the encrypted data, please encrypt your payload and try again"
}

☑️
Fix
Check your encrypted payload or the keys used for encryption.

Validation Errors

Occurs when the input does not meet API requirements.


{
    "status": "failed",
    "statusCode": "01",
		"message": "The 'amount' field is required."
}

☑️
Fix
Check your request body for required fields, correct data types, and valid values.

Resource Errors

Returned when a resource (like a transaction or customer) does not exist.

{
	"error": {
	"code": 404,
	"message": "Not Found",
	"description": "The resource you are trying to access does not exist."
	}
}

☑️
Fix
Confirm the endpoint and resource ID are correct.

Rate Limiting

Triggered when you exceed the allowed request rate.

{
	"error": {
	"code": 429,
	"message": "Too Many Requests",
	"description": "Rate limit exceeded. Please try again later."
	}
}

☑️
Fix
Optimize your quieries, implement a back off mechanism and retry after a short delay.

Server Errors

Issues on our side. Typically rare. Errors with status code 5xx.

{
	"error": {
	"code": 500,
	"message": "Internal Server Error",
	"description": "An unexpected error occurred on the server."
	}
}

📘
Fix
Retry after a few seconds. If persistent, contact support.

Contact Us

If you encounter errors not covered in this documentation, or need help debugging a response, please reach out to our Support Team:

Email: hello@transactworlddigital.com

We’re happy to help ensure your integration goes smoothly.