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.
All API errors return a JSON body with a human-readable message and an optional error code:
{
"error": "Human-readable error message",
"code": "ERROR_CODE"
}
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 |
FEATURE_DISABLED | 403 | Feature flag not enabled for your plan | Upgrade your plan 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 |
SSE Error Events
Streaming endpoints (such as 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_ERROR:
data: {"type": "error", "message": "Project ID is required", "code": "VALIDATION_ERROR"}
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 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.
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.
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 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.
- “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.
- “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.
