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

> ## Agent Instructions
> Company name is Akhara AI (never Rubric AI). Keep lowercase rubric/rubrics only when meaning grading criteria.
> Expert Review (docs path talent/) is enterprise BYO experts for audit and review: invite customer specialists; do not pitch Akhara recruiting or a public expert career portal. RLHF and domain writing are secondary work types.
> Prefer concrete API examples against public hosts: Environments eval API https://agi.akhara.ai, Control plane PDP https://api.akhara.dev, Evaluation https://app.akhara.ai / https://api.akhara.ai, Expert Review portal https://talent.akhara.ai.
> Do not invent a public hostname for private orchestrators or env API internals.
> Do not confuse control-plane latches with Environments confirmation latches.
> Environments SDK/API examples: curl against https://agi.akhara.ai. Evaluation SDK: from akhara import Akhara and AKHARA_API_KEY.
> Start with /llms.txt for the docs index and OpenAPI links; fetch individual pages as .md exports.

# Errors & Status Codes

> HTTP status codes, error formats, and troubleshooting guide for the Akhara API.

## Overview

The Akhara API uses conventional HTTP status codes to indicate success or failure. Errors include a structured JSON body with details to help you diagnose and fix issues.

***

## HTTP Status Codes

### Success Codes

| Code             | Description                                                                |
| ---------------- | -------------------------------------------------------------------------- |
| `200 OK`         | Request succeeded. Response body contains requested data.                  |
| `201 Created`    | Resource created successfully. Response contains the new resource.         |
| `202 Accepted`   | Request accepted for async processing. Check status endpoint for progress. |
| `204 No Content` | Request succeeded. No response body (e.g., DELETE operations).             |

### Client Error Codes

| Code                       | Description                                                        |
| -------------------------- | ------------------------------------------------------------------ |
| `400 Bad Request`          | Invalid request parameters or body. Check the error details.       |
| `401 Unauthorized`         | Missing or invalid API key.                                        |
| `403 Forbidden`            | Valid API key but insufficient permissions for this action.        |
| `404 Not Found`            | Requested resource does not exist.                                 |
| `409 Conflict`             | Resource conflict (e.g., duplicate name, concurrent modification). |
| `413 Payload Too Large`    | Request body exceeds size limit.                                   |
| `422 Unprocessable Entity` | Valid JSON but semantic validation failed.                         |
| `429 Too Many Requests`    | Rate limit exceeded. See `Retry-After` header.                     |

### Server Error Codes

| Code                        | Description                                                     |
| --------------------------- | --------------------------------------------------------------- |
| `500 Internal Server Error` | Unexpected server error. Contact support if persistent.         |
| `502 Bad Gateway`           | Upstream service unavailable. Retry with backoff.               |
| `503 Service Unavailable`   | Service temporarily unavailable. Check status page.             |
| `504 Gateway Timeout`       | Request timed out. Retry with smaller payload or simpler query. |

***

## Error Response Format

All errors return a consistent JSON structure:

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_field",
    "message": "The 'name' field is required",
    "param": "name",
    "details": {
      "field": "name",
      "expected": "string",
      "received": null
    },
    "request_id": "req_abc123xyz"
  }
}
```

### Error Fields

| Field        | Type   | Description                                     |
| ------------ | ------ | ----------------------------------------------- |
| `type`       | string | Error category (see below)                      |
| `code`       | string | Specific error code for programmatic handling   |
| `message`    | string | Human-readable error description                |
| `param`      | string | Parameter that caused the error (if applicable) |
| `details`    | object | Additional context (varies by error type)       |
| `request_id` | string | Unique request ID for support inquiries         |

***

## Error Types

### `authentication_error`

Issues with API key authentication.

| Code              | Description                           | Resolution                             |
| ----------------- | ------------------------------------- | -------------------------------------- |
| `invalid_api_key` | API key is malformed or doesn't exist | Check key format, regenerate if needed |
| `expired_api_key` | API key has expired                   | Generate a new key in dashboard        |
| `revoked_api_key` | API key was revoked                   | Generate a new key in dashboard        |

```json theme={null}
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid",
    "request_id": "req_abc123"
  }
}
```

### `authorization_error`

Valid authentication but insufficient permissions.

| Code                       | Description                  | Resolution                            |
| -------------------------- | ---------------------------- | ------------------------------------- |
| `insufficient_permissions` | User lacks required role     | Request access from admin             |
| `project_access_denied`    | No access to this project    | Join project or check assignment      |
| `phi_access_denied`        | PHI access not granted       | Request PHI access with justification |
| `credential_required`      | Clinical credential required | Verify credentials in dashboard       |

```json theme={null}
{
  "error": {
    "type": "authorization_error",
    "code": "phi_access_denied",
    "message": "PHI access requires explicit grant for this project",
    "details": {
      "project": "proj_abc123",
      "required_grant": "phi_access"
    }
  }
}
```

### `invalid_request_error`

Request structure or parameters are invalid.

| Code                     | Description                     | Resolution                      |
| ------------------------ | ------------------------------- | ------------------------------- |
| `missing_required_field` | Required field not provided     | Add the missing field           |
| `invalid_field_type`     | Field has wrong data type       | Check expected type             |
| `invalid_field_value`    | Value doesn't match constraints | Check allowed values            |
| `invalid_json`           | Request body is not valid JSON  | Fix JSON syntax                 |
| `unknown_field`          | Unrecognized field in request   | Remove unknown field            |
| `invalid_cursor`         | Pagination cursor is invalid    | Start pagination from beginning |

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_field_value",
    "message": "Invalid value for 'modality': must be one of 'voice', 'notes', 'imaging'",
    "param": "modality",
    "details": {
      "received": "audio",
      "allowed": ["voice", "notes", "imaging"]
    }
  }
}
```

### `resource_error`

Issues with the requested resource.

| Code                 | Description             | Resolution                         |
| -------------------- | ----------------------- | ---------------------------------- |
| `resource_not_found` | Resource doesn't exist  | Check resource ID                  |
| `resource_deleted`   | Resource was deleted    | Resource cannot be recovered       |
| `resource_conflict`  | Conflicting operation   | Retry or resolve conflict          |
| `duplicate_resource` | Resource already exists | Use existing or choose unique name |

```json theme={null}
{
  "error": {
    "type": "resource_error",
    "code": "resource_not_found",
    "message": "Dataset 'ds_xyz789' not found",
    "details": {
      "resource_type": "dataset",
      "resource_id": "ds_xyz789"
    }
  }
}
```

### `validation_error`

Semantic validation of request data failed.

| Code                       | Description                          | Resolution                    |
| -------------------------- | ------------------------------------ | ----------------------------- |
| `invalid_evaluator_config` | Evaluator configuration invalid      | Check evaluator documentation |
| `invalid_sample_schema`    | Sample doesn't match modality schema | Fix sample structure          |
| `invalid_rubric`           | Akhara configuration invalid         | Check akhara format           |
| `invalid_date_range`       | Date range is invalid                | Ensure start \< end           |

```json theme={null}
{
  "error": {
    "type": "validation_error",
    "code": "invalid_evaluator_config",
    "message": "Unknown protocol 'cardiac_arrest' for red_flag_detection evaluator",
    "param": "evaluators[1].config.protocols",
    "details": {
      "evaluator": "red_flag_detection",
      "invalid_protocols": ["cardiac_arrest"],
      "valid_protocols": ["chest_pain", "stroke", "sepsis", "pediatric_fever"]
    }
  }
}
```

### `rate_limit_error`

Request rate limit exceeded.

| Code                        | Description                  | Resolution                  |
| --------------------------- | ---------------------------- | --------------------------- |
| `rate_limit_exceeded`       | Too many requests            | Wait and retry with backoff |
| `concurrent_limit_exceeded` | Too many concurrent requests | Reduce parallelism          |

```json theme={null}
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "details": {
      "limit": 100,
      "window": "60s",
      "retry_after": 30
    }
  }
}
```

### `quota_error`

Usage quota exceeded.

| Code                        | Description                  | Resolution                     |
| --------------------------- | ---------------------------- | ------------------------------ |
| `sample_quota_exceeded`     | Sample storage limit reached | Upgrade plan or delete samples |
| `evaluation_quota_exceeded` | Evaluation limit reached     | Upgrade plan or wait for reset |
| `reviewer_quota_exceeded`   | Reviewer seat limit reached  | Upgrade plan                   |

```json theme={null}
{
  "error": {
    "type": "quota_error",
    "code": "sample_quota_exceeded",
    "message": "Sample storage quota exceeded. Current: 100,000 / Limit: 100,000",
    "details": {
      "current_usage": 100000,
      "quota_limit": 100000,
      "upgrade_url": "https://app.akhara.ai/settings/billing"
    }
  }
}
```

### `server_error`

Internal server errors.

| Code                  | Description                  | Resolution                           |
| --------------------- | ---------------------------- | ------------------------------------ |
| `internal_error`      | Unexpected server error      | Retry; contact support if persistent |
| `service_unavailable` | Service temporarily down     | Check status page; retry later       |
| `timeout`             | Request processing timed out | Reduce payload size; retry           |

```json theme={null}
{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again or contact support.",
    "request_id": "req_abc123xyz"
  }
}
```

***

## Error Handling Best Practices

### Retry Logic

Implement exponential backoff for retryable errors:

```python theme={null}
import time
from akhara import Akhara, RubricError, RateLimitError, ServerError

client = Akhara()

def with_retry(func, max_retries=3):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError as e:
            if attempt == max_retries - 1:
                raise
            wait_time = e.retry_after or (2 ** attempt)
            time.sleep(wait_time)
        except ServerError as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

# Usage
result = with_retry(lambda: client.evaluations.create(...))
```

### Error Categories

Handle errors by category:

```python theme={null}
from akhara import (
    RubricError,
    AuthenticationError,
    AuthorizationError,
    InvalidRequestError,
    ResourceError,
    RateLimitError,
    QuotaError,
    ServerError
)

try:
    evaluation = client.evaluations.create(...)
except AuthenticationError:
    # Re-authenticate or prompt for new API key
    refresh_api_key()
except AuthorizationError as e:
    # Log and notify admin
    notify_admin(f"Access denied: {e.message}")
except InvalidRequestError as e:
    # Fix request parameters
    log.error(f"Invalid param '{e.param}': {e.message}")
except ResourceError as e:
    # Handle missing resource
    if e.code == "resource_not_found":
        create_resource_first()
except RateLimitError as e:
    # Wait and retry
    time.sleep(e.retry_after)
    retry()
except QuotaError:
    # Notify about quota
    alert_quota_exceeded()
except ServerError:
    # Retry with backoff
    retry_with_backoff()
```

### Logging Errors

Always log the `request_id` for support:

```python theme={null}
try:
    result = client.datasets.create(...)
except RubricError as e:
    logger.error(
        "Akhara API error",
        extra={
            "error_type": e.type,
            "error_code": e.code,
            "request_id": e.request_id,
            "message": e.message
        }
    )
    raise
```

***

## Common Error Scenarios

### Creating a Dataset

| Error                             | Likely Cause          | Fix                                |
| --------------------------------- | --------------------- | ---------------------------------- |
| `missing_required_field: project` | No project ID         | Add `project` parameter            |
| `invalid_field_value: modality`   | Wrong modality        | Use `voice`, `notes`, or `imaging` |
| `resource_not_found: project`     | Project doesn't exist | Check project ID                   |
| `authorization_error`             | No project access     | Request project membership         |

### Running an Evaluation

| Error                             | Likely Cause             | Fix                  |
| --------------------------------- | ------------------------ | -------------------- |
| `invalid_evaluator_config`        | Wrong evaluator settings | Check evaluator docs |
| `resource_not_found: dataset`     | Dataset deleted          | Use existing dataset |
| `validation_error: empty_dataset` | Dataset has no samples   | Add samples first    |
| `quota_error`                     | Evaluation limit reached | Upgrade or wait      |

### Submitting a Review

| Error                             | Likely Cause              | Fix                  |
| --------------------------------- | ------------------------- | -------------------- |
| `credential_required`             | Not a verified reviewer   | Verify credentials   |
| `phi_access_denied`               | No PHI access for review  | Request PHI access   |
| `validation_error: invalid_grade` | Grade value not in akhara | Check akhara options |

***

## Status Page

Check real-time API status at:

**[status.akhara.ai](https://status.akhara.ai)**

Subscribe to incident notifications for proactive alerts.

***

## Related

<CardGroup cols={2}>
  <Card title="Rate Limits" icon="gauge" href="/evaluation/api-reference/rate-limits">
    Understanding rate limits and quotas
  </Card>

  <Card title="Support" icon="headset" href="https://akhara.ai/support">
    Contact support with your request\_id
  </Card>
</CardGroup>