> ## 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 Error Reference and Troubleshooting

> Understand HTTP status codes, the JSON error envelope format, and how to resolve common Braintest API errors.

The Braintest API uses standard HTTP status codes and a consistent JSON error envelope. This page explains what each status means, shows the exact response shape, and provides guidance for resolving the most common errors.

## HTTP status codes

| Status | Meaning           | What to do                                                                                      |
| ------ | ----------------- | ----------------------------------------------------------------------------------------------- |
| 200    | Success           | The request succeeded. Inspect the `successful` field inside the envelope.                      |
| 400    | Bad Request       | The request body or query parameters are invalid. Check the `messages` array for details.       |
| 401    | Unauthorized      | The `API-KEY` header is missing or invalid. Verify the key value from the organizer panel.      |
| 403    | Forbidden         | The key is valid but the request is blocked. See the 403 section below for causes.              |
| 404    | Not Found         | The requested resource (record, roadmap, or endpoint) does not exist. Check the token or URL.   |
| 409    | Conflict          | The resource is in a state that prevents the operation. See the 409 section below for examples. |
| 429    | Too Many Requests | API rate limit exceeded. Wait before retrying. See [Rate Limits](/reference/rate-limits).       |

## Error response envelope

All error responses follow the same envelope structure as successful ones:

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "Error message describing what went wrong"
  ]
}
```

* `data`: always `null` on error
* `successful`: always `false` on error
* `messages`: array of human-readable error strings; may contain multiple messages

## Common 400 errors

A `400` response means the request syntax or parameters are invalid. Common causes include:

**Invalid mobile number**

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "Invalid mobile number. Must be 11 digits starting with 09."
  ]
}
```

Mobile numbers must be exactly 11 digits and start with `09`.

**Invalid filter parameter**

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "Invalid filter value provided."
  ]
}
```

Check that query filters like `filter__is_finished` use boolean strings (`true` or `false`).

**Missing required profile field**

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "The name field is required."
  ]
}
```

Ensure all required profile fields (`name`, `mobile`, `birth`, `is_male`) are present and valid.

## 401 vs 403

These two statuses both indicate access problems, but the cause and fix differ.

**401 Unauthorized**

The `API-KEY` header is missing or the key does not exist.

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "Authentication credentials were not provided."
  ]
}
```

What to check:

* The header name is exactly `API-KEY`
* The value matches the key generated in the organizer panel
* The key is active and has not been revoked

**403 Forbidden**

The key is valid, but the request is blocked for another reason.

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "Access denied."
  ]
}
```

Common causes:

* The API key is expired or suspended
* The requesting IP address is not allowlisted
* A payment or quota issue exists on the account
* The record or roadmap requires profile authentication first (`auth_required: true`)

## 409 conflicts

A `409` response means the resource is in a state that prevents the requested operation.

**Already completed**

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "This record has already been completed."
  ]
}
```

You cannot re-authenticate or re-submit answers for a finished record.

**Duplicate external\_id**

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "The external_id has already been used for this organizer."
  ]
}
```

The `external_id` must be unique per organizer. Choose a different value.

**Roadmap record authentication error**

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "This record belongs to a roadmap. Use the roadmap authentication endpoint."
  ]
}
```

You called `/record/{token}/auth/` for a record that is part of a roadmap. Use `/roadmap/{token}/auth/` instead.

**Incomplete roadmap**

```json theme={"dark"}
{
  "data": null,
  "successful": false,
  "messages": [
    "All test records must be completed before generating AI analysis."
  ]
}
```

Finish every test record in the roadmap before calling `/roadmap/{token}/generate/`.

## Rate limits

The Braintest API enforces per-minute and per-hour request limits on every API key. When you exceed either limit, the API returns HTTP `429 Too Many Requests`. See [Rate Limits](/reference/rate-limits) for the exact values and handling guidance.

## General troubleshooting tips

1. Always check the `messages` array first. It contains the most specific explanation.
2. Verify the base URL is `https://braintest.ir/api/v2/` and the path is correct.
3. Confirm the `API-KEY` header is present and properly formatted.
4. For `400` errors, validate your JSON body against the field requirements in the relevant guide.
5. For `409` errors, check the current resource status before retrying the operation.