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

# Introduction

> Introductory essay for integrating with Busha

The **Busha API** is designed to provide businesses with tools for borderless financial transactions and operations, enabling modern, global money management. It serves as the backbone for facilitating:

* Creation and management of multi-currency balances
* Retrieval of real-time cryptocurrency rates
* Substantial data insights for business owners

## Authentication

All API requests require a **Bearer Token** for authentication, passed in the `Authorization` header.
Your authorization value is a base64 encoded value of your api key and your secret key.
You can obtain API tokens via your Busha user or business account. Authentication is mandatory to ensure secure and authorized interactions with the API.
The API keys from the dashboard provides a base64 encoding of the your authorization tokens.

Your generated Key should look like this:
`VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=`

Example Header:

```curl theme={null}
Authorization: Bearer VURtNXhWcHueantkpaiewjo0S044MWsadfojienuoxRTiWDJaeWJaTGxxanZ3Ym10OU1RZnVWajVW=
```

## Error Handling

Standardized error responses ensure predictable interactions. Errors are detailed for easy debugging and understanding:

| **Error Code**        | **HTTP Status Code** | **Description**                    |
| --------------------- | -------------------- | ---------------------------------- |
| `bad_request`         | 400                  | Invalid input or malformed request |
| `unauthorized`        | 401                  | Invalid or missing authentication  |
| `not_found`           | 404                  | Resource not found                 |
| `service_unavailable` | 503                  | Server error                       |

Basic Error Example:

```json theme={null}
{
  "error": {
    "name": "bad_request",
    "message": "Invalid input data"
  }
}
```

Schema Error Body Example:

```json theme={null}
{
  "error": {
    "name": "bad_request",
    "message": "Invalid input data"
  },
  "schema": {
    "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
    "fix": "Ensure that the object being submitted, matches the schema correctly"
  }
}
```

Field Error Body Example:

```json theme={null}
{
  "error": {
    "name": "bad_request",
    "message": "Invalid input data"
  },
  "fields": {
    "field1": [
      {
        "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
      },
    ],
    "field2": [
      {
        "reason": "The request body is defined as an object. However, it does not meet the schema requirements of the specification",
      }
    ],
  }
}
```

## Pagination

Pagination uses cursors provided as:
The API supports **cursor-based pagination** for endpoints with large datasets. Pagination uses a `next_cursor` and `previous_cursor` returned in the response.
Example Response Format:

```json theme={null}
{
  "current_entries_size": 10,
  "next_cursor": "base64_cursor_value",
  "previous_cursor": "base64_previous_cursor_value"
}
```

## Rate Limiting

Rate limits determine how many API calls can be made in a rolling minute. This ensures fair and optimized use of system resources.

The rate limits allowed by each resource will be provided with the header:

```curl theme={null}
x-rate-limit 100
```

If this header does not exist, then the rate limit is set at a default 100 req/min

Requests exceeding the allocated quota will receive a `429 Too Many Requests` response.

## Common Parameters

Common parameters enhance consistency across endpoints:

| **Parameter Name** | **Location** | **Description**          | **Example**              |
| ------------------ | ------------ | ------------------------ | ------------------------ |
| `X-BU-PROFILE-ID`  | Header       | User profile identifier  | `BUS_qwejinoiuiqw93ejjw` |
| `id`               | Path         | Unique NanoID identifier | `dpt_jweqafajsndiun34fd` |
| `cursor`           | Query        | Pagination cursor        | `base64_cursor_string`   |

#### Paginated Response Example

```json theme={null}
{
  "status": "success",
  "message": "Data retrieved",
  "pagination": {
    "next_cursor": "value_for_next_page",
    "current_entries_size": 20
  },
  "data": [...]
}
```