# Error Codes

Reference of error codes returned by the Cubit API.

## Error Response Format

All errors follow this structure:

```json
{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {
    "field": "additional_context"
  }
}
```

## Authentication Errors (401)

### `missing_api_key`

No API key was provided in the request.

```json
{
  "error": "missing_api_key",
  "message": "API key is required. Include it in the Authorization header as 'Bearer <key>'.",
  "details": {}
}
```

### `invalid_api_key`

The API key is invalid, expired, or malformed.

```json
{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or expired.",
  "details": {}
}
```

**Resolution:**

* Check for typos in the API key
* Verify the key hasn't been rotated
* Generate a new key in your dashboard

## Authorization Errors (403)

### `insufficient_tier`

The endpoint requires a higher tier than your current plan.

```json
{
  "error": "insufficient_tier",
  "message": "This endpoint requires professional tier. Your tier: sandbox",
  "details": {
    "required_tier": "professional",
    "current_tier": "sandbox",
    "upgrade_url": "https://cubit.maidenlabs.tools/pricing"
  }
}
```

### `job_not_in_tier`

The requested occupation is not available on your tier.

```json
{
  "error": "job_not_in_tier",
  "message": "Job 17-2051.00 is not available in the sandbox tier.",
  "details": {
    "soc_code": "17-2051.00",
    "current_tier": "sandbox",
    "upgrade_url": "https://cubit.maidenlabs.tools/pricing"
  }
}
```

**Resolution:**

* Sandbox tier includes top 100 occupations only
* Upgrade to Professional for full occupation access

## Not Found Errors (404)

### `job_not_found`

No occupation exists with the given SOC code.

```json
{
  "error": "job_not_found",
  "message": "No job found with SOC code: 99-9999.00",
  "details": {
    "soc_code": "99-9999.00"
  }
}
```

### `task_not_found`

No task exists with the given ID.

```json
{
  "error": "task_not_found",
  "message": "No task found with ID: invalid_id",
  "details": {
    "task_id": "invalid_id"
  }
}
```

### `skill_not_found`

No skill/requirement exists with the given element ID.

```json
{
  "error": "skill_not_found",
  "message": "No skill found with element ID: 9.Z.9.z",
  "details": {
    "element_id": "9.Z.9.z"
  }
}
```

### `region_not_found`

No region exists with the given MSA code.

```json
{
  "error": "region_not_found",
  "message": "No region found with MSA code: 99999",
  "details": {
    "msa_code": "99999"
  }
}
```

## Validation Errors (400)

### `invalid_request`

Request parameters failed validation.

```json
{
  "error": "invalid_request",
  "message": "Query parameter 'q' is required",
  "details": {
    "field": "q"
  }
}
```

## Rate Limit Errors (429)

### `rate_limit_exceeded`

Daily or burst rate limit exceeded.

```json
{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Please wait or upgrade your plan.",
  "details": {
    "resets_at": "2026-01-25T00:00:00Z"
  }
}
```

**Resolution:**

* Wait for the reset time
* Upgrade to a higher tier
* Implement caching to reduce requests

## Server Errors (500)

### `database_error`

A database operation failed.

```json
{
  "error": "database_error",
  "message": "A database error occurred.",
  "details": {}
}
```

### `embedding_error`

The embedding service (for semantic search) failed.

```json
{
  "error": "embedding_error",
  "message": "Failed to generate embedding for semantic search.",
  "details": {}
}
```

**Resolution:**

* Fall back to keyword search
* Retry after a delay

### `configuration_error`

Server configuration issue.

```json
{
  "error": "configuration_error",
  "message": "Server configuration error.",
  "details": {}
}
```

## Handling Errors in Code

```python
from cubit import (
    CubitClient,
    CubitError,
    AuthenticationError,
    AuthorizationError,
    NotFoundError,
    RateLimitError,
    ServerError,
)

client = CubitClient("your_api_key")

try:
    job = client.get_job(soc_code)
    
except AuthenticationError:
    # Re-authenticate or prompt for new key
    pass
    
except AuthorizationError as e:
    # Check tier, suggest upgrade
    print(f"Upgrade required: {e.message}")
    
except NotFoundError:
    # Handle missing resource
    pass
    
except RateLimitError as e:
    # Wait and retry
    import time
    time.sleep(e.retry_after or 60)
    
except ServerError:
    # Retry with backoff
    pass
    
except CubitError as e:
    # Catch-all for other API errors
    print(f"API error: {e.status_code} - {e.message}")
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maidenlabs.tools/resources/error-codes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.