> For the complete documentation index, see [llms.txt](https://doc.threatreaper.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.threatreaper.ai/api-and-developer-reference/error-codes.md). # ⚠️ Error Codes LockThreat returns standard HTTP status codes. Unless otherwise noted, error bodies look like: ```json { "detail": "A human-readable description of what went wrong" } ``` Every unhandled server error also returns a `correlation_id` — include it when contacting support. *** ### 400 Bad Request The request was understood but can't be fulfilled as-is (missing precondition, bad combination of fields). ```json { "detail": "No active AI connector found. Connect an AI model in the Connectors section first." } ``` ```json { "detail": "AI generation is not yet supported for connector type 'custom'. Supported: OpenAI, Anthropic, Azure OpenAI." } ``` **Fix:** read the message — it names the missing precondition (usually a connector, project, or field combination). *** ### 401 Unauthorized Your credential is missing, invalid, or expired. ```json { "detail": "Invalid API key" } ``` ```json { "detail": "API key is inactive" } ``` ```json { "detail": "API key expired" } ``` ```json { "detail": "Invalid or expired token." } ``` ```json { "detail": "Your session has expired. Please log in again." } ``` **Fix:** * API key: confirm it's active and not revoked (`GET /api-keys/list`), and that you're sending it in the `X-API-Key` header. * JWT: refresh it (`POST /refresh`) or sign in again — access tokens expire after 15 minutes by default. *** ### 403 Forbidden You're authenticated, but not allowed to do this specific thing. ```json { "detail": "Insufficient credits" } ``` ```json { "detail": "Insufficient credits for ai_probe. Current balance: 0, requested deduction: 10" } ``` ```json { "detail": "Not a member of this project" } ``` ```json { "detail": "Missing required permission: TR_FIREWALL_POLICIES:CREATE_POLICY" } ``` ```json { "detail": "Connector is not active" } ``` **Fix:** * Credits: ask your administrator to top up your organisation's credit balance (Settings > License & Plan in the console). * Permission: ask an administrator to grant the named permission to your role in **Settings > Roles**. * Project membership: confirm you're calling with a `projectId` that belongs to your organisation and that you're assigned to it. *** ### 404 Not Found The resource ID you referenced doesn't exist — or doesn't exist **for your organisation** (LockThreat returns 404 rather than 403 for cross-tenant lookups, so existence isn't leaked across organisations). ```json { "detail": "Project not found in your organization" } ``` ```json { "detail": "Policy not found" } ``` ```json { "detail": "Connector not found" } ``` ```json { "detail": "Scan not found" } ``` **Fix:** double-check the ID and that you're using the right organisation/project context. *** ### 409 Conflict The request conflicts with existing state. ```json { "detail": "An agent named 'prod-agent-01' already exists. Please choose a different name." } ``` **Fix:** choose a different name, or reuse/update the existing resource instead of creating a new one. *** ### 422 Unprocessable Entity The request body doesn't match the expected schema (missing required field, wrong type, bad format), or a value is semantically invalid. ```json { "detail": "Invalid UUID format" } ``` ```json { "detail": "Invalid ID format" } ``` For plain schema validation errors (missing fields, wrong types), the API returns the first validation error FastAPI found, for example: ```json { "detail": "field required: prompt" } ``` **Fix:** check every required field listed in 🌐 API Endpoints and 💻 Request & Response Examples is present and the right type. *** ### 429 Too Many Requests You've hit a rate limit, a login lockout, or run out of request allowance for that endpoint. **Login lockout:** ```json { "detail": "Too many failed attempts. Please try again later." } ``` **Generic per-endpoint rate limit:** ```json { "detail": { "error": "rate_limit_exceeded", "message": "Too many requests to /v2/raksha/tr_firewall_analyze. Limit: 100 per 60s.", "limit": 100, "window": 60, "reset_at": 1760345000, "retry_after": 42 } } ``` **Response headers accompanying a 429:** ``` Retry-After: 42 X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1760345000 X-RateLimit-Window: 60 ``` **Fix:** back off for `retry_after` seconds (or until `X-RateLimit-Reset`) before retrying. For the autonomous decisions endpoint specifically, the default limit is 30 requests per 60 seconds per user. *** ### 500 Internal Server Error Something failed on LockThreat's side. ```json { "detail": "Internal server error", "correlation_id": "4f8a1c2e-9b3d-4e5f-8a6b-7c8d9e0f1a2b", "message": "An unexpected error occurred. Please contact support with the correlation ID." } ``` **Fix:** retry once after a short delay; if it persists, contact LockThreat support with the `correlation_id` from the response (also returned in the `X-Correlation-ID` header). *** ### 503 Service Unavailable A downstream dependency (for example the ML analysis engine, or a connected AI provider) is temporarily unavailable. **Fix:** retry with exponential backoff. If you're calling `/api/autonomous/analyze` and it persists, fall back to `/v2/raksha/tr_firewall_analyze` directly, or fail safe in your application (don't silently allow unanalyzed prompts through). *** ### Quick reference | Code | Meaning | Typical fix | | ---- | ---------------------------------- | ----------------------------------------------------- | | 400 | Bad request / missing precondition | Read the message, fix the named field or precondition | | 401 | Missing/invalid/expired credential | Refresh JWT or check your API key | | 403 | Authenticated but not allowed | Check role permissions or credit balance | | 404 | Resource not found (or not yours) | Check the ID and active project | | 409 | Conflict with existing resource | Rename, or update instead of create | | 422 | Request body validation failed | Check required fields/types | | 429 | Rate limited or locked out | Back off and retry after `Retry-After` | | 500 | Server error | Retry; contact support with `correlation_id` | | 503 | Dependency temporarily unavailable | Retry with backoff; consider a fallback path | ### Next * Back to 🔌 API & Developer Reference --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://doc.threatreaper.ai/api-and-developer-reference/error-codes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.