Errors & Status Codes

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:

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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:

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:

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:

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 Subscribe to incident notifications for proactive alerts.

Rate Limits

Understanding rate limits and quotas

Support

Contact support with your request_id

​Overview

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Error Response Format

​Error Fields

​Error Types

​authentication_error

​authorization_error

​invalid_request_error

​resource_error

​validation_error

​rate_limit_error

​quota_error

​server_error

​Error Handling Best Practices

​Retry Logic

​Error Categories

​Logging Errors

​Common Error Scenarios

​Creating a Dataset

​Running an Evaluation

​Submitting a Review

​Status Page

​Related