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

# Responses and status codes

> Understand the MasterID JSON response envelope, the difference between request IDs and session IDs, and how to handle pending and unauthenticated responses.

MasterID returns a consistent JSON envelope for every API call. Learn the difference between the request ID, the session ID, and the collection reference so you route results correctly in your integration.

## Success envelope

A completed request returns HTTP 200 with a JSON object containing `id` and `data`.

**id** `string`

The API request ID. Every response, including errors, includes this value.

**data** `object`

The operation payload. Its shape depends on the endpoint.

### Example: wallet balance

```json theme={null}
{
  "id": "<REQUEST_ID>",
  "data": {
    "currency": "UGX",
    "balance": 50000
  }
}
```

## Error envelope

An error response returns `{ id?, error }`. The `id` field is present when MasterID generated a request ID before detecting the failure.

```json theme={null}
{
  "id": "<REQUEST_ID>",
  "error": "Invalid input"
}
```

For per-code troubleshooting, see [Errors](https://docs.masterid.co.ug/concepts/errors.md).

## Pending response (202)

Operations that finish asynchronously return HTTP 202. The envelope still contains `id` and `data`, but the data indicates the operation is processing.

* Verification submissions return a `sessionId` and a pending status.
* Collection requests return a `reference` and a pending status.

Store the returned identifier (session ID or reference) and poll or wait for the webhook. Do not submit the same request again with a different key.

## Request ID vs session ID vs collection reference

| Identifier | Source | Purpose |
| - | - | - |
| Request ID | Every API response | Ties a single HTTP call to API history and logs |
| Session ID | `POST /verifications` response | Identifies a verification check; use it with `GET /verifications/{sessionId}` |
| Collection reference | `POST /collections` response | Identifies a payment request; use it with `GET /collections/{reference}` |

> [!WARNING]
>
> The request ID and the session ID are different values. Store the session ID or collection reference so you can retrieve final results later.

## Unauthenticated browser visits

If you open an API URL in a browser without credentials, MasterID returns service information only. No workspace data, balance, or records are exposed.

## Response-handling helper

Use a small helper to normalise every response and extract the request ID for logging.

```typescript response-handler.ts theme={null}
const BASE_URL = "https://masterid.me/api/public/v1";

async function callMasterID(path: string, init?: RequestInit) {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...init,
    headers: {
      "X-API-Key": process.env.MASTERID_API_KEY!,
      "X-API-Secret": process.env.MASTERID_API_SECRET!,
      "Content-Type": "application/json",
      ...init?.headers,
    },
  });

  const body = await res.json().catch(() => ({}));

  if (!res.ok) {
    const err: any = new Error(body.error || `HTTP ${res.status}`);
    err.status = res.status;
    err.requestId = body.id ?? null;
    throw err;
  }

  return {
    requestId: body.id,
    data: body.data,
    status: res.status,
  };
}

// Usage
const { requestId, data } = await callMasterID("/wallet");
console.log("request", requestId, "balance", data.balance);
```

```python response_handler.py theme={null}
import os
import requests

BASE_URL = "https://masterid.me/api/public/v1"


def call_masterid(path, **kwargs):
    headers = {
        "X-API-Key": os.environ["MASTERID_API_KEY"],
        "X-API-Secret": os.environ["MASTERID_API_SECRET"],
        "Content-Type": "application/json",
    }
    headers.update(kwargs.pop("headers", {}))

    res = requests.request(
        kwargs.pop("method", "GET"),
        f"{BASE_URL}{path}",
        headers=headers,
        **kwargs,
    )

    try:
        body = res.json()
    except Exception:
        body = {}

    if not res.ok:
        err = Exception(body.get("error") or f"HTTP {res.status_code}")
        err.status = res.status_code
        err.request_id = body.get("id")
        raise err

    return {
        "request_id": body.get("id"),
        "data": body.get("data"),
        "status": res.status_code,
    }


# Usage
result = call_masterid("/wallet")
print("request", result["request_id"], "balance", result["data"]["balance"])
```

> [!TIP]
>
> Always log the request ID. It makes support requests faster when you need to trace a specific call.


## Related topics

- [Errors](https://docs.masterid.co.ug/concepts/errors.md)
- [GET /collections/{reference}](https://docs.masterid.co.ug/api-reference/collections/get-collection.md)
- [POST /collections](https://docs.masterid.co.ug/api-reference/collections/create-collection.md)
- [POST /verifications](https://docs.masterid.co.ug/api-reference/verifications/create-verification.md)
- [GET /catalog](https://docs.masterid.co.ug/api-reference/catalog/get-catalog.md)


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