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

# Error Reference

> HTTP status codes, error codes, and troubleshooting guide

# Error Reference

This page documents the error responses returned by the thig.ai API, including HTTP status codes, application-specific error codes, and troubleshooting tips.

## Error Response Format

All API errors return a JSON body with a human-readable message and an optional error code:

```json theme={null}
{
  "error": "Human-readable error message",
  "code": "ERROR_CODE"
}
```

The `error` field is always present. The `code` field is included when a specific application error code applies. Some endpoints may include additional fields such as `details` for validation errors.

## HTTP Status Codes

| Code    | Meaning               | Common Cause                                                         |
| ------- | --------------------- | -------------------------------------------------------------------- |
| **200** | OK                    | Request succeeded                                                    |
| **201** | Created               | Resource created successfully                                        |
| **400** | Bad Request           | Invalid input, missing required fields, or malformed JSON            |
| **401** | Unauthorized          | Missing or invalid session cookie / API key                          |
| **403** | Forbidden             | Insufficient role permissions or feature not enabled for your plan   |
| **404** | Not Found             | Resource does not exist or belongs to a different organization       |
| **409** | Conflict              | Duplicate resource (e.g., a version with that number already exists) |
| **422** | Unprocessable Entity  | Request body failed schema validation                                |
| **429** | Too Many Requests     | Rate limit exceeded                                                  |
| **500** | Internal Server Error | Unexpected server-side error                                         |

## Error Codes

| Code                   | HTTP Status | Description                                         | Resolution                                                                                         |
| ---------------------- | ----------- | --------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `UNAUTHORIZED`         | 401         | Missing or invalid session or API key               | Log in again or verify your API key is correct                                                     |
| `FORBIDDEN`            | 403         | Insufficient role permissions for this action       | Contact your organization admin for elevated access                                                |
| `RATE_LIMITED`         | 429         | Too many requests in a short period                 | Wait and retry with exponential backoff                                                            |
| `VALIDATION_ERROR`     | 400         | Request body failed schema validation               | Check required fields, types, and formats against the [API Reference](/api-reference/introduction) |
| `FEATURE_DISABLED`     | 403         | Feature flag not enabled for your plan              | Upgrade your [plan](/user-guide/billing) or contact support                                        |
| `GENERATION_ERROR`     | 500         | AI provider failed to generate content              | Retry the request; if the error persists, try switching to a different AI provider                 |
| `USAGE_LIMIT_EXCEEDED` | 403         | Monthly usage quota reached for your plan           | Upgrade your plan or wait for your usage to reset at the next billing cycle                        |
| `PROVIDER_ERROR`       | 502         | Upstream AI provider returned an error              | Try a different AI provider or retry after a brief wait                                            |
| `NOT_FOUND`            | 404         | The requested resource does not exist               | Verify the resource ID and that it belongs to your organization                                    |
| `DUPLICATE`            | 409         | A resource with that identifier already exists      | Use a different name, key, or version number                                                       |
| `ACCOUNT_LOCKED`       | 403         | Account locked after too many failed login attempts | Wait 15 minutes for automatic unlock, or use password reset                                        |
| `MFA_REQUIRED`         | 403         | Two-factor authentication code required             | Enter the 6-digit code from your authenticator app                                                 |
| `IP_BLOCKED`           | 403         | Request IP not in organization's allowlist          | Contact your admin to add your IP to the [allowlist](/user-guide/security#ip-allowlisting)         |
| `APPROVAL_REQUIRED`    | 403         | Action requires approval workflow completion        | Wait for designated approvers to approve your request                                              |
| `GRACE_PERIOD_EXPIRED` | 403         | Subscription past due and grace period has expired  | Update payment method to restore plan access                                                       |
| `API_KEY_EXPIRED`      | 401         | REST API key has passed its expiration date         | Create a new API key or update the expiration on the existing one                                  |
| `API_KEY_INACTIVE`     | 401         | REST API key has been deactivated                   | Re-activate the key from Settings > Developer                                                      |

## SSE Error Events

Streaming endpoints (such as [Chat](/api-reference/chat) and PRD generation) use Server-Sent Events (SSE) to deliver responses incrementally. When an error occurs during streaming, it is sent as an SSE event rather than an HTTP error status:

```
data: {"type": "error", "message": "Generation failed", "code": "GENERATION_ERROR"}
```

Validation errors caught before streaming begins are also delivered as SSE events with the code `VALIDATION_ERROR`:

```
data: {"type": "error", "message": "Project ID is required", "code": "VALIDATION_ERROR"}
```

Your client should listen for events where `type` is `"error"` and handle them appropriately -- for example, by displaying the message to the user and closing the connection.

## Rate Limits

thig.ai uses a dual rate limiting system to protect the platform and ensure fair usage:

* **Tier-based limits** -- Based on your subscription plan (Free, Pro, Business, Enterprise). These govern monthly AI token usage, project counts, and other resource quotas. See [Billing](/user-guide/billing) for plan details.
* **Endpoint-based limits** -- Anti-abuse limits applied per endpoint and per IP address. These prevent excessive request volumes regardless of plan tier.

When you exceed a rate limit, the API returns a `429` status with the `RATE_LIMITED` error code.

<Tip>
  Check the `Retry-After` header in 429 responses. It indicates how many seconds to wait before retrying. Implement exponential backoff in your integration to handle rate limits gracefully.
</Tip>

## Troubleshooting Tips

Common issues and how to resolve them:

* **"401 Unauthorized" on every request** -- Your session has likely expired. Log out and log back in, or generate a fresh API key from **Settings > API Keys**.
* **"403 Feature disabled"** -- The feature you are trying to use is not enabled for your current plan. Check your [plan limits](/user-guide/billing) and upgrade if needed.
* **"429 Rate limited"** -- You are sending too many requests. Implement exponential backoff and respect the `Retry-After` header. Consider batching requests where possible.
* **"500 on AI endpoints"** -- The AI provider may be experiencing issues. Try switching to a different provider in your project settings or [BYOK configuration](/user-guide/settings).
* **"Empty response from AI"** -- The conversation or PRD content may be too short for the AI to analyze meaningfully. Add more context to your conversation before generating.
* **"Export fails"** -- Ensure the project has a generated PRD before attempting to export. If exporting to Notion or Google Docs, verify that the [integration is connected](/user-guide/settings#integrations).
* **"404 on a resource you just created"** -- The resource may belong to a different organization context. Verify you are authenticated as a member of the correct organization.
* **"409 Conflict on version creation"** -- A PRD version with that number already exists. The system auto-increments version numbers, but manual creation may cause conflicts. Use the next available version number.
* **"403 Approval required"** -- An approval workflow is configured for this action. Your request has been submitted for review. Wait for designated approvers to approve it.
* **"403 IP blocked"** -- Your IP is not in the organization's allowlist. Contact your admin to add your IP or CIDR range.
* **"401 API key expired"** -- Your REST API key has passed its expiration date. Create a new key or extend the expiration from **Settings > Developer**.