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

# API Response Envelope Format

> Understand the unified JSON envelope that wraps every Braintest API response, including success and error shapes.

Every response from the Braintest API returns the same top-level envelope, regardless of endpoint or HTTP status code. This consistency makes it easier to parse responses in your integration code.

## Envelope schema

All JSON responses share this structure:

```json theme={"dark"}
{
  "data": {},
  "successful": true,
  "messages": []
}
```

## Field reference

| Field        | Type                   | Description                                                                                             |
| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------- |
| `data`       | object, array, or null | The actual payload for the request. Contains endpoint-specific data on success. Set to `null` on error. |
| `successful` | boolean                | `true` when the request succeeded and `data` is valid. `false` when an error occurred.                  |
| `messages`   | array of strings       | Empty on success. Contains one or more human-readable error descriptions on failure.                    |

## Success example

```json theme={"dark"}
{
  "data": {
    "token": "rec_abc123",
    "test_title": "DASS-21",
    "status": 2,
    "auth_required": true
  },
  "successful": true,
  "messages": []
}
```

## Failure example

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "Authentication failed. The provided mobile number is invalid.",
    "Name must contain only Persian letters and be at most 50 characters."
  ]
}
```

## Error handling notes

* The API does not use a separate `message` or `devMessage` field. All error text lives in the `messages` array.
* Multiple validation errors can appear in a single response. Check every entry in `messages` before showing feedback to the user.
* HTTP status codes still matter: 401 and 403 indicate authentication issues, 404 indicates a missing resource, and 422 indicates validation errors. Always inspect `successful` alongside the status code.

<Note>
  Because `data` is `null` on error, your parser should check `successful` before attempting to read fields from `data`.
</Note>