> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rapidtopup.com.ng/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Format

> All API responses use a consistent JSON envelope. Learn the structure here.

## Content Type

All responses are returned with:

```
Content-Type: application/json
```

Always send `Content-Type: application/json` in your **request headers** for `POST` endpoints.

***

## Success Response

```json theme={null}
{
  "status": "success",
  "data": { ... }
}
```

***

## Sandbox (Test Mode) Responses

When authenticated with a test key (`rtu_test_sk_...`), responses include an explicit `"environment": "sandbox"` property indicating that the transaction was executed in the mock testing environment:

```json theme={null}
{
  "status": "success",
  "environment": "sandbox",
  "data": { ... }
}
```

***

## Error Response

```json theme={null}
{
  "status": "error",
  "message": "Human-readable description of what went wrong"
}
```

***

## Validation Error Response

When your request body fails validation, the API returns a detailed field-level error map:

```json theme={null}
{
  "message": "The phone number field must be 11 digits.",
  "errors": {
    "phone_number": [
      "The phone number field must be 11 digits."
    ],
    "type": [
      "The type field is required."
    ]
  }
}
```

> [!TIP]
>
> Always check the `errors` object on `422` responses. It tells you exactly which fields failed and why.

***

## Duplicate Request Response

When an `idempotency_key` is reused:

```json theme={null}
{
  "message": "Duplicate request detected. Returning original transaction.",
  "transaction": { ... },
  "is_duplicate": true
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.