---
updatedAt: 2026-08-21T10:43:10.000Z
agentTools:
  projectIndex: https://transactpay.readme.io/llms.txt
---

# Errors

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.

<Callout icon="ℹ️" theme="info">
  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.
</Callout>

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

<aside>

✅

**Fix**

</aside>

<Callout icon="☑️" theme="default">
  ### Fix

  Add the correct Authorization header:

  `Authorization: Bearer YOUR_SECRET_KEY`
</Callout>

### Encryption Errors

Occurs when the payload has not been properly encrypted.

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

<Callout icon="☑️" theme="default">
  ### Fix

  Check your encrypted payload or the keys used for encryption.
</Callout>

### Validation Errors

Occurs when the input does not meet API requirements.

```json

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

<Callout icon="☑️" theme="default">
  ### Fix

  Check your request body for required fields, correct data types, and valid values.
</Callout>

### **Resource Errors**

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

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

<Callout icon="☑️" theme="default">
  ### Fix

  Confirm the endpoint and resource ID are correct.
</Callout>

### **Rate Limiting**

Triggered when you exceed the allowed request rate.

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

<Callout icon="☑️" theme="default">
  ### Fix

  Optimize your quieries, implement a back off mechanism and retry after a short delay.
</Callout>

### **Server Errors**

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

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

<Callout icon="📘" theme="info">
  ### Fix

  Retry after a few seconds. If persistent, contact support.
</Callout>

### **Duplicate Responses**

Ensure to retry with a new unique reference and confirm the status of the initial reference passed.

```json
{
    "status": "failed",
    "statusCode": "14",
    "message": "This order reference: (xx) already exists, please generate a unique one and try again"
}
```

## **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.